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Intended Audience 

This manual is intended for all users of the VAX/VMS operating system. 

If you are not familiar with an interactive computer system, you should read 
the Introduction to VAX/VMS before using this manual. 


Structure of This Document 

This manual is tutorial in nature; it provides an overview of the concepts 

underlying the DIGITAL Command Language and VAX/VMS operating 

system. Following is a breakdown of the subject matter presented in this 

manual, according to chapter. 

• Chapter 1, Overview, describes how to access the system and enter 
commands. This chapter includes tables summarizing terminal function 
keys and line editing terminal function keys, as well as process privileges 
and resource quotas. 

• Chapter 2, Syntax Rules for Entering DCL Commands, describes the 
syntax rules for issuing DCL commands, including how to enter command 
verbs, parameters, qualifiers, and date and time values. 

• Chapter 3, File Specifications, explains how to enter file specifications. 
This chapter describes how the system interprets the components of a 
file specification, including the default value that is assumed if you omit 
a component. It also shows how to use wildcard characters to indicate 
groups of files. 

• Chapter 4, Logical Names, explains how to use logical names to refer to 
physical devices, directories, and files. This chapter describes logical name 
access modes and attributes, logical name tables, and search lists (logical 
names with multiple equivalence strings). 

• Chapter 5, Symbols and Expressions, explains how to create and 
use symbols, and how the system evaluates expressions. Symbols 
have a variety of uses, including providing customized abbreviations 
for command strings and passing variables in command procedures. 
Expressions are values that are evaluated and associated with symbols. 

• Chapter 6, Symbol Substitution, explains how the DCL command 
interpreter replaces symbol names with their current values when it 
processes a command string. 

• Chapter 7, Protection, explains how to protect devices, directories, and 
files according to user identification codes (UICs) and access control lists 
(ACLs). 
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Associated Documents 

For a detailed description of each DCL command and lexical function, see the 
VAX/VMS DCL Dictionary , the reference companion to this manual. 

For an introduction to the VAX/VMS operating system and the DIGITAL 
Command Language, see the Introduction to VAX/VMS. This manual is 
especially recommended for novice users and those users lacking experience 
with interactive computer systems. 

The Guide to Using DCL and Command Procedures on VAX/VMS describes 
good practices for constructing command procedures with DCL commands 
and lexical functions. 

Each manual in the VAX/VMS utilities documentation describes the DCL 
command that invokes the utility, any commands that you can enter while 
running the utility, and other information. For all utilities documented in that 
volume, the VAX/VMS DCL Dictionary provides only a brief description and 
format information. 

The VAX/VMS System Messages and Recovery Procedures Reference Manual 
explains any error and warning messages you may receive. In most cases, 
however, you will not need to refer to this manual, because it will be obvious 
from the message text and other information on your screen what action (if 
any) to take. 

The Introduction to the VAX/VMS Document Set describes the new organization 
of the document set. This manual shows how the individual manuals fit 
together and relate to each other. 


Conventions Used in This Document 


Convention 

[retI 


|CTRL/x| 


$ SHOW TIME 

04-FEB-1986 11:55:22 

$ TYPE MYFILE.DAT 


file-spec, . . . 


Meaning 

A symbol with a one- to three-character abbreviation 
indicates that you press a key on the terminal, for 
example, |ret| . 

The phrase CTRL/x indicates that you must press 
the key labeled CTRL while you simultaneously 
press another key, for example, CTRL/C, CTRL/Y, 
CTRL/O. 

Command examples show all output lines or 
prompting characters that the system prints or 
displays in black letters. All user-entered commands 
are shown in red letters. 

Vertical series of periods, or ellipsis, mean either 
that not all the data that the system would display 
in response to the particular command is shown or 
that not all the data a user would enter is shown. 

Horizontal ellipsis indicates that additional 
parameters, values, or information can be entered. 
















Preface 



Convention 

Meaning 

[logical-name] 

Square brackets indicate that the enclosed item 
is optional. (Square brackets are not, however, 
optional in the syntax of a directory name in a 
file specification or in the syntax of a substring 
specification in an assignment statement.) 

quotation marks 
apostrophes 

The term quotation marks is used to refer to double 
quotation marks ("). The term apostrophe (') is 
used to refer to a single quotation mark. 
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New and Changed Features 


The DIGITAL Command Language now allows hyphens (-) to be used in file 
specifications. This is a new feature for VAX/VMS Version 4.4. 


xv 














Overview 


The DIGITAL Command Language (DCL) is the language through which 
you communicate with the VAX/VMS operating system. DCL contains an 
extensive set of commands that allow you to do tasks such as: 

• Develop and execute programs 

• Work with files 

• Work with disks, tapes, and other devices 

• Get information about the system 

• Modify your work environment 

DCL also provides commands for system managers to establish a computing 
environment in which resources are used efficiently and adequate security is 
provided. 

You can use DCL in two modes: interactive and noninteractive. In interactive 
mode, you issue commands directly from your terminal. When you issue 
a command procedure (a file containing DCL commands) interactively, you 
must wait for the command procedure to finish executing before you can 
continue entering commands from your terminal. 

In noninteractive mode, the system creates another process to execute 
commands on your behalf. Batch jobs and network processes use DCL in 
noninteractive mode. For example, when you submit a command procedure 
for batch execution, a separate process is created to execute the command 
procedure. After you submit the command procedure for batch execution, 
you can continue to use your terminal interactively while your batch job is 
executing. 

The following chapter gives an overview of how to access the system and 
issue commands interactively. It also describes your terminal function 
keys and control characters. The chapter ends with tables that summarize 
VAX/VMS user privileges and resource quotas. 


1 Process Characteristics 

When you log in to the VAX/VMS operating system, an environment is 
created from which you can issue commands. This environment is called 
your process. The system obtains the characteristics that are unique to your 
process from the user authorization file (UAF). The UAF lists all users who 
can access the system and defines the characteristics for each user's process. 
The system manager usually maintains the UAF. 
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Some of the characteristics associated with your process include: 

• An account number or name, which your installation uses to keep track of 
the system resources used. 

• A user identification code (UIC), which provides you with a unique 
identifying number. Part of your UIC identifies the group to which 
you belong. Within a group, users are allowed to share files or system 
resources more freely than between groups. 

• A default disk device and directory name, which the system uses to locate 
and catalog files that you create or use. 

• Default devices from which the system reads command and program input 
and to which the system writes messages. 

• A set of privileges and resource quotas that define what system resources 
or system functions you, or programs you execute, are allowed to use. 
Tables 1-3 and 1-4 at the end of this chapter list the specific privileges 
and quotas that the system allows. 


1.2 Accessing the System 

To access the system, you must identify yourself and provide sufficient 
evidence that you are an authorized user. The number of steps and the 
specific information you must enter depend on the security needs of your site, 
as determined by the system manager or the security manager. 

1 If your terminal is not connected to a terminal server, press the RETURN 
key (you may have to press RETURN several times). If the "secure server" 
terminal characteristic is set, you must press the BREAK key. 

If your terminal is connected to a terminal server, refer to that product's 
documentation for information on connecting to the VAX/VMS system. 

2 If you are not prompted for your user name, either the system is not 
running or a "system password" is required from your terminal. If a 
system password is required, consult your system manager or security 
manager. For more information on system passwords, see the Guide to 
VAX/VMS System Security. 

3 When you are prompted, enter your user name and your password. For 
example: 

\m 

Username: PATTI 1 RET| 

Password: 

When you enter the password, the system does not echo it; that is, the 
system accepts the input line but does not display it on the terminal. 

Your system may require an additional (secondary) password. If so, a 
second "Password" prompt appears, and you must enter the secondary 
password. 

For a complete discussion of passwords and the system's treatment of 
them, see the Guide to VAX/VMS System Security. 
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4 After the system confirms that you are an authorized user, it may display 
information like the following: 

• List of disconnected processes that you own, if any 

• Welcome message 

• Date and time of last interactive and noninteractive logins 

• Number of login failures since last successful login, if any 

• Possibly messages relating to the system 

The system indicates that it is ready to accept commands by displaying a 
dollar sign ($), the DCL prompting character, as shown below: 

Welcome to VAX/VMS Version 4.0 on node BOSTON 


$ 


1.3 Entering DCL Commands 

DCL commands consist of words from the English language (generally verbs) 
that describe what you want the system to do. 

The following example shows a PRINT command and the system's response, 
as they would appear on a terminal: 

$ PRINT/C0PIES=2 MYFILE.DAT ! Print the file [ret] 

Job MYFILE (queue BOSTON.PRINT, entry 384) started on B0ST0N$LPA0 

$ 

The elements of the above command include: 


$ 

The default system prompt for command input. 

You can change this prompt with the SET PROMPT 
command. 

PRINT 

The command name, requesting the system to queue 
a file for printing on the system printer. 

/COPIES=2 

A qualifier to the PRINT command, requesting that 
two copies of the specified file be printed. 

MYFILE.DAT 

The command parameter, naming the file to be 
printed. 

! Print the file 

A comment. A comment is always preceded by an 
exclamation point. A comment is strictly for your 
information and is ignored by DCL. 

[ret] 

The RETURN key. Pressing this key after entering 
a full command line terminates the command input; 
the system begins processing the command. Note 
that examples in this manual do not explicitly show 
the RETURN key being pressed following commands; 
you can assume that all user input shown in examples 
must be terminated by pressing the RETURN key 
unless stated otherwise. 


See Chapter 2 for complete details on the syntax rules for entering DCL 
commands. 
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1.4 Command Prompting 

When you enter a command at the terminal, you need not enter the entire 
command all at once. If you enter a command that requires parameters and 
you do not specify the parameters, the command interpreter prompts you for 
them. For example: 

$ PRINT/C0PIES=2 
.File: MYFILE.DAT 

In this example, no parameter is entered, so the system prompts for a file 
specification. A line beginning with an underscore indicates that the system 
is waiting for additional input. 

When you are prompted for an optional parameter, you can press RETURN 
to complete the command sequence without specifying the parameter, as the 
following example illustrates: 

$ ALLOCATE 
.Device: DM: 

.Log.Name: IRET| 

_DMB1: ALLOCATED 

In the above example, the ALLOCATE command is entered with no 
parameters; the command interpreter begins prompting for all parameters. 
The second prompt is for an optional parameter. A null entry, signaled by 
RETURN, terminates the command entry. 

If you enter a CTRL/Z after a command prompt, DCL will ignore the 
command and will display the DCL prompt so you can enter a new 
command. 


1.5 System Messages 

When you enter a command incorrectly, the command interpreter issues 
a descriptive error message telling you what was wrong. For example, if 
you specify more than one parameter for a command that accepts a single 
parameter, you receive the message: 

y,DCL-W-MAXPARM, too many parameters - reenter command with fewer parameters 

You must then retype the command correctly. 

In addition to error messages, the system issues messages that merely warn 
or inform you of a particular condition. 

Messages begin with a percent sign or hyphen and have the following general 
format: 

7.FACILITY-L-IDENT, text 

FACILITY is a mnemonic for the operating system facility or the program 
issuing the message, L is a severity level indicator (S for success, I for 
informational, W for warning, E for error, and F for fatal), and IDENT is 
a shorthand code for the message text. When a series of messages is issued, 
messages after the first one are prefixed by a hyphen rather than a percent 
sign. Note that it is possible to change the error message format display with 
the SET MESSAGE command. 

The text of DCL error messages describes the cause of the problem and then 
suggests a possible corrective action. 











Overview 


The VAX/VMS System Messages and Recovery Procedures Reference Manual lists 
the system messages and describes what you can do to correct an error; see 
this volume if you get an error message that you do not understand. 


1.6 Online Sources of Information (SHOW and HELP) 

DCL provides a group of SHOW commands that you can use to obtain 
information about the system and your process. For example, to find out 
about users currently logged into your system, you can type the SHOW 
USERS command. See the description of SHOW in the VAX/VMS DCL 
Dictionary for a list of the SHOW commands. 

The system also provides an online HELP facility that gives information about 
DCL commands. To use the HELP facility, type the HELP command followed 
by the topic you want information about. For example: 

$ HELP PRINT 

The system responds by displaying a description of the PRINT command. It 
also lists PRINT topics that you can get more information about. For example, 
you type the following command to obtain information about qualifiers to the 
PRINT command. 

$ HELP PRINT COMMAND.QUALIFIERS 

The HELP command displays a description of each PRINT command qualifier. 

By default, an interactive form of HELP is invoked that prompts you for 
individual topics or subtopics. See the description of the HELP command in 
the VAX/VMS DCL Dictionary for more information. You can also type the 
following command to get more information about using the HELP facility. 

$ HELP HELP 


1.7 Using the Terminal 

There are many types of terminals, and each has its own operating 
characteristics. To determine the current characteristics of your terminal, 
issue the SHOW TERMINAL command. You can change some of these 
characteristics with the SET TERMINAL command. By default, changes made 
with the SET TERMINAL command apply only to the current session. 

Your terminal has standard function keys that allow you to perform terminal 
functions. Certain functions are performed by using control keys. To use a 
control key, press the CTRL key and hold it down while you press the other 
specified key. For example, to enter CTRL/Y, hold the CTRL key down and 
then press the Y key. 

Your terminal also has special line editing keys that allow you recall, edit, 
and reissue previous commands. To use the line editing keys, the line editing 
characteristic (set with SET TERMINAL/LINE—EDIT) must be in effect. 

Table 1-1 lists the standard terminal function keys and describes their use; 
Table 1-2 lists the line editing function keys that are enabled with SET 
TERMINAL/LINE—EDIT. In addition, some of the frequently used keys are 
described in the following sections. 
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Table 1-1 Terminal Function Keys 


Key 

Function 

RETURN 

Transmits the current line to the system for processing. 
(On some terminals, the RETURN key is labeled CR.) 

Before a terminal session, initiates login sequence. 

CTRL/B and 

Displays the last command line issued. If pressed again. 

Up arrow 

displays the previous command in the recall buffer. 

The recall buffer stores the 20 most recently issued 
commands. 

CTRL/C and 

During command entry, cancels command processing. 

F6 1 

CTRL/C is displayed as “Cancel". 

Certain applications enable CTRL/C as the cancel key. 

For these applications, CTRL/C cancels the operation in 
progress. If CTRL/C is not enabled, then the action is 
changed to an interrupt (CTRL/Y). 

CTRL/I 

Duplicates the function of the TAB key. 

CTRL/K 

Advances the current line to the next vertical tab stop. 

CTRL/L 

Causes the terminal to go to the beginning of the next 
page. This use of this key is ignored when the line 
editing characteristic is enabled. 

CTRL/O 

Alternately suppresses and continues display of output 
to the terminal. CTRL/O is displayed as "Output off" and 
"Output on". 

CTRL/Q 

Restarts terminal output that was suspended by CTRL/S. 

CTRL/R 

Retypes the current input line and leaves the cursor 
positioned at the end of the line. 

CTRL/S 

Suspends terminal output until CTRL/Q is pressed. 

CTRL/T 

Momentarily interrupts terminal output to display a line 
of statistical information about the current process. 

SET CONTROL=T must be specified in the system-wide 
login command file, or by the user (in LOGIN.COM or 
interactively). The display includes your node and user 
name, the time, the name of the image you are running, 
and information about system resources you have used 
during your current terminal session. 

CTRL/U 

Discards the current input line. 

CTRL/X 

Discards the current line and deletes data in the type- 
ahead buffer. 

CTRL/Y 

During command entry, interrupts command processing. 
CTRL/Y echoes as "Interrupt". You can disable CTRL/Y 
with the command SET NOCONTROL=Y. 

Under most conditions, CTRL/Y will return the user 
to the DCL prompt. The program running will still be 
active. You can enter any of the commands listed in 
Table 2-1 and then continue the program by entering 
the CONTINUE command. 

CTRL/Z and 

Signals the end of the file for data entered from the 

F10 1 

terminal. CTRL/Z is displayed as "Exit". 


’This key is available only on an LK201 keyboard. 
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Table 1-1 (Cont.) Terminal Function Keys 


Key 


Function 

DELETE 


Deletes the last character entered at the terminal. (On 
some terminals, the DELETE key is labeled RUBOUT.) 

TAB 


Moves the printing element or cursor on the terminal to 
the next tab stop on the terminal. The system provides 
tab stops at every eighth character position on a line. 
Tab settings are hardware terminal characteristics that 
can generally be modified by the user. 

Down arrow 


Displays the next line in the recall buffer. 

Table 1-2 

Line Editing Terminal Function Keys 

Key 


Function 

CTRL/A and 
F14 1 


Switches between overstrike mode and insert mode. 

The default mode (as set with SET TERMINAL/LINE_ 
EDIT) is reset at the beginning of each line. 

CTRL/D and 
Left arrow 


Moves the cursor one character to the left. 

CTRL/E 


Moves the cursor to the end of the line. 

CTRL/F and 
Right arrow 


Moves the cursor one character to the right. 

CTRL/H and 
BACKSPACE and 
F12 1 

Moves the cursor to the beginning of the line. 

CTRL/J and 
LINEFEED and 
F13 1 


Deletes the word to the left of the cursor. 

CTRL/U 


Deletes characters from the beginning of the line to the 
cursor. (This overrides the standard CTRL/U function, 
which discards the current input line.) 

CTRL/V 


Allows you to enter one of the line editing function 
keys without the key performing its line editing function. 
CTRL/V acts as a quote character, allowing you to input 
a control character without having the terminal interpret 
the character. 

F7,F8,F9,F1 1 


Reserved to DIGITAL 

^his key is available only on an LK201 keyboard. 


1.7.1 Deleting Characters 

The DELETE key backspaces over the most recently entered character and 
deletes it. On a hardcopy terminal, the letters deleted are displayed between 
backslash characters so you can see what is being deleted. On a video display 
terminal, pressing DELETE actually erases the character from the screen and 
moves the cursor backwards. Note that the key that performs the delete 
function is marked RUBOUT on some terminals and is marked <CE3 on 
LK201 keyboards. 
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Note: Do not use the BACKSPACE key to delete characters when you are 

entering DCL commands; the BACKSPACE key does not delete characters. 


1.7.2 Deleting Lines 

If you have not enabled the line editing function keys, you can use the 
CTRL/U key sequence to delete an entire line. For example, if you make 
several mistakes on a particular line and want to cancel the line and reenter 
it, use CTRL/U as shown below: 

$ PRNT/CIPY=2~U 
$ PRINT/C0PIES=2 MYFILE.DAT 

When you cancel a line with CTRL/U, the system ignores the line and 
prompts you for the next line. 

If you have enabled the line editing function keys, you can use CTRL/U to 
delete characters from the beginning of the line to the cursor. 


1.7.3 Canceling Commands 

If you are entering commands in response to prompts and want to discard the 
entire command you have entered (not just the most recently entered line), 
use CTRL/C or CTRL/Y, as shown below: 

$ PRINT/C0PIES=3 
.File: MYFILE.DAT~Y 

Interrupt 

In this example, the PRINT command was entered correctly, and the system 
prompted for the name of a file to print. However, while entering the file 
name, the user decided not to enter the command at all, and used CTRL/Y to 
discard the entire command. 

You can also use CTRL/C to cancel or CTRL/Y to interrupt the execution of 
a program. 


1.7.4 Editing Commands 

You can use the function keys in Table 1-2 to edit command lines. In order 
to use the line editing function keys, the line editing characteristic (set with 
SET TERMINAL/LINE _EDIT) must be in effect. 

Note: If you are using an application that uses the function keys that are 

enabled by line editing, you should not use the SET TERMINAL/LINE_ 
EDIT while you run that application. If the line editing functions are 
enabled, many keys will not be available to the user application. 

You can edit a command line in either overs trike or insert mode. In overs trike 
mode, the character you type replaces the character indicated by the cursor. 

In insert mode, the character you type is inserted to the left of the cursor. 
Your default editing mode is established by the SET TERMINAL command; 
you can use SET TERMINAL/LINE _EDIT/INSERT or SET TERMINAL 
/LINE—EDIT/OVERSTRIKE. You can change editing modes by pressing 
CTRL/A. 
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For example, after you type the following command (but before you terminate 
the command by pressing RETURN) you notice that you made a spelling 
mistake: 

$ TYPE [MYDRECTORYDVERY_LONG.DAT 

In this command, the directory name should be [MYDIRECTORY]. You can 
use the left arrow key to move the cursor back to "R" in [MYDRECTORY]. 

If your default editing mode is overstrike, press CTRL/A to switch to insert 
mode, then type the "I". Now, you can press the RETURN key and DCL will 
execute your edited command. 

If you enter more characters than will fit on one line of your terminal screen 
and you do not press the RETURN key, the line will wrap to the next line. If 
this occurs, you can edit only the line where your cursor appears. You cannot 
use the arrow key to move the cursor up to edit characters in the previous 
line. However, you can use the DELETE key, or CTRL/U, to delete all the 
characters in the current line. Then, you can use the DELETE key to move 
the cursor up to the previous line. 


1.7.5 Recalling Commands 

You can recall command lines that you previously entered by using the 
RECALL command, or by using CTRL/B or the up arrow and down arrow 
keys. 

At the DCL command level, you can press CTRL/B or the up arrow key 
up to 20 times, or enter the RECALL/ALL command, to recall the last 20 
commands you have typed. After you recall a command line, you can reissue 
the command by pressing the RETURN key, or you can edit the command 
and then reissue it. You can press the down arrow key to recall the next 
(more recent) command line in the command recall buffer. 

If you are at the DCL level, you can use CTRL/B and the up and down 
arrows for command recall regardless of whether the line editing terminal 
characteristic is set. However, if you are in a utility or an application program, 
CTRL/B and the up arrow key will not perform command recall unless the 
line editing characteristic is set (see the description of the SET TERMINAL 
command in the VAX/VMS DCL Dictionary). Moreover, in most utilities or 
application programs, CTRL/B and the up arrow key can be used to recall 
only the most recently entered command. 


1.7.6 Displaying the Time 

You can use CTRL/T to display the current time. SET CONTROL=T must 
be specified in the system-wide login command file, or by the user (in 
the LOGIN.COM file or interactively). CTRL/T also displays your node 
and username, the name of the image you are running, and information 
about system resources you have used during your current terminal session, 
You can also use the CTRL/T key to determine if the system is operating. 
(CTRL/T will not echo information if the system is temporarily hung or if 
your terminal is set to NOBROADCAST.) 
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1.7.7 Defining Terminal Keys 

You can use the DEFINE/KEY command to create key definitions for certain 
terminal keys. A key definition is a string of characters that you assign to a 
particular terminal key. When a key is defined, you can press the terminal 
key instead of typing the characters. A key definition usually contains all or 
part of a command string. When you press a defined key, the command is 
displayed on your terminal and/or executed. Keypad definitions allow you to 
customize your terminal keypad so you can enter DCL commands with fewer 
keystrokes. 

Some defineable keys are enabled for definition all the time (like keys PF1 
through PF4 and keys FI 7 through F20 on VT200 series terminals). Other 
keys, including KPO through KP9, PERIOD, COMMA, and MINUS, need to 
be enabled for definition purposes. You must issue either the SET TERMINAL 
/APPLICATION or the SET TERMINAL/NONUMERIC command before 
using these keys. For a list of keys that you can define and for more 
information on how to create definitions, see the description of DEFINE 
/KEY in the VAX/VMS DCL Dictionary . 


1.8 Tailoring the Command Language 

VAX/VMS provides several ways to tailor the command language. These 

techniques allow you to increase the power of the command language and to 

customize DCL to meet your needs. 

You can use the following techniques to tailor the command language: 

• Defining symbols that you can use as synonyms for command names. Use 
the = (Assignment Statement) and the := (String Assignment) commands 
to define symbols. 

• Creating new, DCL-like commands to execute programs that you write. 
You can create new commands by defining a foreign command (described 
in Chapter 5) or by using the Command Definition Utility (described in 
the VAX/VMS Command Definition Utility Reference Manual.) 

• Writing command procedures containing groups of commands that you 
frequently use. You can execute your command procedure to issue the 
commands, rather than issuing each command individually. 

• Writing a login command procedure that the system automatically executes 
every time you log in. Your login command procedure should be named 
LOGIN.COM. It can contain any DCL commands that you want to 
execute every time you log in. See the Guide to Using DCL and Command 
Procedures on VAX/VMS for guidelines for writing command procedures. 
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1.9 


Summary of VAX/VMS Process Privileges and Resource 
Quotas 


Tables 1-3 and 1-4 summarize the full set of process privileges and resource 
quotas. The system manager sets each user's privileges and resource quotas 
in the user authorization file (UAF). If you need special quotas or privileges 
to use DCL commands, the command descriptions in the VAX/VMS DCL 
Dictionary note these restrictions. 


Table 1-3 Process Privileges 


Privilege 

[NO]ACNT 

[NO]ALL 

[NO]ALLSPOOL 

[NOJALTPRI 

[NOJBUGCHK 

[NO]BYPASS 

[NOJCMEXEC 

[NO]CMKRNL 

[NOJDETACH 

[NOJDIAGNOSE 

[NO]EXQUOTA 

[NO]GROUP 

[NOJGRPNAM 

[NOJGRPPRV 


[NO]LOG_IO 

[NOJMOUNT 

[NO]NETMBX 

[NOJOPER 

[NOJPFNMAP 

[NO]PHY_IO 

[NO]PRMCEB 


Meaning 

Allows/disallows the process to create processes for which 
no accounting messages are written 

Allows/disallows all privileges for the process 
Allows/disallows the process to allocate spooled devices 
Allows/disallows the process to set priority values 

Allows/disallows the process to make bug check error log 
entries 

Allows/disallows the process to bypass UIC protection 

Allows/disallows the process to change its mode to 
executive 

Allows/disallows the process to change its mode to kernel 
Allows/disallows the process to create detached processes 

Allows/disallows the process to issue diagnostic I/O 
requests 

Allows/disallows the process to exceed its quotas 

Allows/disallows the process to control other processes in 
the same group 

Allows/disallows the process to place names in the group 
logical name table 

Allows/disallows the process to access files in its own 
group with all the access rights granted to the system 
category of user for those files 

Allows/disallows the process to issue logical I/O requests 
to a device 

Allows/disallows the process to issue a mount volume QIO 
request 

Allows/disallows the process to create a network device 
Allows/disallows the process to perform operator functions 

Allows/disallows the process to create or delete sections 
mapped by page frame number 

Allows/disallows the process to issue physical I/O requests 
to a device 

Allows/disallows the process to create permanent common 
event flag clusters 
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Privilege 

Meaning 

[NO]PRMGBL 

Allows/disallows the process to create permanent global 
sections 

[NO]PRMMBX 

[NO]PSWAPM 

[NO]READALL 

Allows/disallows the process to create permanent mailboxes 
Allows/disallows the process to alter its swap mode 

Allows/disallows the process to bypass existing restrictions 
that would otherwise prevent the process from reading a file 

[NO]SECURITY 

Allows/disallows the process to perform security-related 
functions such as enabling or disabling security audits or 
setting the system password 

[NO]SETPRV 

Allows/disallows the process to give higher privileges to 
other processes 

[NO]SHARE 

Allows/disallows the process to assign a channel to a 
device, even if the channel is allocated to another process or 
subprocess 

[NO]SHMEM 

Allows/disallows the process to create or delete data 
structures in shared memory 

[NOJSYSGBL 

Allows/disallows the process to create system global 
sections 

[NO]SYSLCK 

Allows/disallows the process to request locks on system- 
wide resources 

[NO]SYSNAM 

Allows/disallows the process to place names in the system 
logical name table 

[NOJSYSPRV 

Allows/disallows access to files and other resources as if 
the user has a system UIC 

[NO]TMPMBX 

[NO]VOLPRO 

[NO]WORLD 

Allows/disallows the process to create temporary mailboxes 
Allows/disallows the process to override volume protection 

Allows/disallows the process to control all other processes 
in the system 


Table 1-4 Resource Quotas 


Name 

Quota 

ASTLM 

AST (asynchronous system trap) limit 

BIOLM 

Buffered I/O limit 

BYTLM 

CPUTIME 

DIOLM 

Buffered I/O byte count (buffer space) quota 

CPU time limit 

Direct I/O limit 

ENQLM 

FILLM 

JTQUOTA 

MAXACCTJOBS 

MAXDETACH 

MAXJOBS 

Enqueue limit 

Open file quota 

Initial byte quota for job logical name table 

Maximum active processes for an account 

Maximum detached processes for a user name 

Maximum active processes for a user name 
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Table 1-4 (Cont.) Resource Quotas 


Name 

Quota 

PGFLQUOTA 

Paging file quota 

PRCLM 

Subprocess quota 

SHRFILLM 

Maximum number of open shared files 

TQELM 

Timer queue entry quota 

WSDEFAULT 

Default working set size 

WSEXTENT 

Working set extent quota 

WSQUOTA 

Working set size quota 
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2 Syntax Rules for Entering DCL Commands 


This section describes the syntax rules for issuing DCL commands. It also 
explains how to interpret the syntax lines in the command descriptions in the 
VAX/VMS DCL Dictionary. 

The section starts with an explanation of the components of a command 
string. Next, it describes rules for: 

• Entering verbs 

• Entering parameters 

• Entering qualifiers 

• Entering date and time values 

• Interrupting command execution 


2.1 


The DCL Command String 


A command string is the complete specification of a DCL command. 
Although you can continue a command on more than one line, the term 
command string is used to define an entire command that is passed to the 
system. The DCL command string can contain the following components: 


Verb 


Specifies the command to be executed. 


Parameter Specifies what the verb acts upon. The DCL command definitions 
describe the parameter values that are allowed for each command. 
Examples of parameter values include file specifications, queue 
names, and logical names. Some commands accept keywords as 
parameters. (A keyword is a predefined word that can be used in 
a certain place.) 

Qualifier Describes or modifies the action taken by the verb. The DCL 

command definitions indicate whether qualifiers can accept values, 
and indicate the types of values that can be specified. 

Label A string used to identify a line in a command procedure. You 

should use labels only within command procedures. 


For example, in the command string: 

$ DIFFERENCES/MODE=ASCII MYFILE.DAT YOURFILE.DAT 

DIFFERENCES is the verb and /MODE is a qualifier that has as its value the 
keyword ASCII. MYFILE.DAT and YOURFILE.DAT are parameters that tell 
the DIFFERENCES command what files to act upon. 

In some cases (such as SHOW LOGICAL or ANALYZE/RMS-FILE) a verb 
name is coupled with a parameter or a qualifier. In these cases the verb and 
parameter or qualifier are used as a pair. If you specify additional parameters 
or qualifiers, they must follow the verb pair. 
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The following example shows a command that contains a verb pair consisting 
of a verb (SHOW) and a parameter (LOGICAL): 

$ SHOW LOGICAL MYDIR 


The additional parameter MYDIR, which provides the name to be translated, 
is specified after the verb pair. If any qualifiers are used, they must be 
specified after the verb pair; qualifiers cannot be placed between SHOW and 


LOGICAL. 


2.2 Rules for Entering Commands 

The general format of a DCL command is: 

[$] [label:] verb [/qualifiers...] parameter[/qualifiers...][...] 

You can precede any command with a dollar sign ($) character. In interactive 
mode the command interpreter ignores the dollar sign. However, it is 
required in command procedures. If a label is used, it must be the first 
item after the dollar sign ($). (Labels are only used in command procedures.) 

Each item in a command string must be delimited, as follows: 

• A label must be terminated with a colon. The colon can be preceded by 
or followed by any number of spaces or tabs. No spaces can be embedded 
within the label name. A label name can contain up to 255 characters. 

• At least one blank character must separate the command name from 
the first parameter, and at least one blank must separate each additional 
parameter from the previous parameter. Multiple spaces and tabs are 
permitted in all cases where a single blank is required. See Section 2.3 for 
more information on entering parameters. 

• Each qualifier must be preceded with a slash (/). The slash can be 
preceded by or followed by any number of spaces or tabs. See Section 2.4 
for more information on entering qualifiers. 

When you enter commands, you can use any combination of uppercase and 
lowercase letters because the command interpreter translates lowercase letters 
to uppercase letters. The command interpreter also compresses multiple blank 
spaces or tabs to a single blank when spaces or tabs are used as delimiters. 

A DCL command string can contain up to 1024 characters after symbols and 
lexical functions have been expanded. However, you can enter only 256 
characters before you must continue the string, as described below. 

Each element in a command string (for example, a file specification or 
qualifier) must be less than or equal to 255 characters. Also, a command 
string can contain a maximum of 128 elements. 
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2.2.1 Continuing Commands on More Than One Line 

You can enter a command string on more than one line by using the 
continuation character, the hyphen. To continue a line, you must enter 
the hyphen as the last element on the line, or the last element before a 
comment. Note that a hyphen, when not used at the end of a line, is treated 
like any other character and is legal in file specifications. For information on 
characters that are legal in file specifications, see Section 3.3. 

When you enter a command interactively and continue the command on 
more than one line, the command interpreter uses the dollar sign preceded 
by an underscore (_$) to indicate that it is still accepting the command. For 
example: 

$ type - 

_$ TAXES.MEM 

Command string continuation is especially useful when you enter a command 
and want to specify many qualifiers, or when you place a command in a 
command procedure file and want to make the procedure more readable. In 
command procedures, do not begin continuation lines with dollar signs. For 
example: 

$ PRINT MYFILE - 
/AFTER=17:00 - 
/C0PIES=2O - 
/NAME="COMGUIDE" 

There is no restriction on the number of continued lines you can use to enter 
a command as long as the expanded command string does not exceed DCL's 
1024-character limit. 


2.2.2 Entering Comments 

Indicate a comment by preceding it with an exclamation point. Comments 

are valid in the following positions: 

• As the first item in a command string after the DCL prompt; in this case, 
the entire line is considered a comment and is not processed except for 
symbol substitutions and lexical functions 

• After the last character in a command string or after a hyphen continuation 
character 

Some examples of valid placement of comments follow: 

$ !THIS ENTIRE LINE IS A COMMENT 

$ PRINT MYFILE - ! PRINT COMMAND COMMENT 

_$ /C0PIES=3 ! 3 COPIES. PLEASE 


2.2.3 Abbreviating Components of the DCL Command String 

You can abbreviate verbs, qualifiers, and keywords when you enter DCL 
command strings. The rules for abbreviating these entities are described in 
the following sections. 

When the DCL command interpreter examines a command string, it examines 
only the first four characters of verb and qualifier names. However, DCL 
examines keyword names in their entirety. 
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2.2.3.1 Abbreviating Command Names 

You can abbreviate a command name to its first four characters. You may 
truncate command names to fewer characters as long as the truncation is 
unique. For example, the TYPE command is currently the only command 
that begins with the character "T" Therefore, the TYPE command could 
be truncated to just one character. The DEALLOCATE and DEASSIGN 
commands, however, have the same first three characters, so these commands 
cannot be truncated to fewer than four characters. 

The following commands are exceptions to the minimum truncation rule 
because they can be truncated to just their first character, even though other 
commands begin with the same character: 

CONTINUE 

DEPOSIT 

EXAMINE 

RUN 


2.2.3.2 Abbreviating Qualifiers and Keywords 

You can truncate any qualifier name to four characters. You can truncate a 
qualifier name to fewer characters if the abbreviation is unique with respect to 
the other qualifiers recognized by the same command. 

Note that many qualifiers permit a negative form. For example, /NOLIST 
is the negative form of the /LIST qualifier. In applying the minimum four- 
character truncation rule, do not count the NO prefix as the first two of 
the four characters. In this case, the minimum truncation that guarantees 
uniqueness is /NOLIST. The slash character (/) is also disregarded in 
counting characters. However, the underscore character is counted, as in 
/BY_OWNER, where the minimum truncation for guaranteed uniqueness is 
/BY_0. 

You can abbreviate keywords to the fewest number of characters that provide 
a unique abbreviation within a set of possible keywords. If you enter more 
characters than are needed to uniquely identify a keyword, you must not 
misspell the keyword. For example, when you use the keyword TRACEBACK 
with the MACRO/DEBUG command, you can abbreviate TRACEBACK to 
TRAC (or even T) with no conflict, but you could not enter TRACBACK or 
any other misspelling. 


2.2.3.3 Abbreviations in Command Procedure Files 

Special considerations apply when you type commands in command 
procedure files. To ensure readability, do not abbreviate commands, 
qualifiers, or keywords. If you do abbreviate any of these items, you should 
never abbreviate to fewer than four characters or you risk the possibility that 
your command procedure may not be compatible with future releases of the 
system. 
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2.3 Rules for Entering Parameters 

The command descriptions in the VAX/VMS DCL Dictionary show the 
parameters that are accepted by each command, and indicate whether 
parameters are optional or required. The command descriptions also indicate 
whether you can enter a list of items for a parameter. For example, the format 
line: 

SET HOST node-name 

shows that the SET HOST command requires a node name as a parameter. 

The square brackets in a format line indicate that a parameter is optional. For 
example, the notation: 

means that you can optionally enter a list of items for a parameter. The list is 
treated as a single parameter. For example, the format line: 

MONITOR class-name[,...] 

shows that you can optionally enter a list of class-names as the parameter. 

Use commas to separate the items in a parameter list. Any number of spaces 
or tab characters can precede or follow the commas. 

You can also separate the items in a parameter list with plus signs. In most 
cases, commas and plus signs are equivalent. However, sometimes they have 
different meanings as separators; plus signs can be concatenation operators 
as well as separators, depending on the context. The parameter descriptions 
in the VAX/VMS DCL Dictionary state how a command interprets commas 
and plus signs. In general, you should not use plus signs as separators unless 
specifically required. 


2.3.1 Entering File Specifications as Parameter Values 

File specifications are the most common type of parameter used by DCL 
commands. See Chapter 3 for complete details on the parts of VAX/VMS file 
specifications. DCL commands can accept input file specifications (files that 
are acted upon by a command) and output file specifications (files that are 
created by a command). 

The command descriptions in the VAX/VMS DCL Dictionary describe how 
each command interprets file specifications. For example, file specifications 
that you enter as parameters to DCL commands are subject to logical name 
translation. However, some commands perform only a single level of logical 
name translation; that is, translation is not iterative. When this is the case, 
the parameter description indicates that fact. 

The command descriptions provide information about defaults for file 
specifications that are entered as parameters. In addition, the command 
descriptions indicate whether the use of wildcards is allowed. 

If you supply a list of file specifications as a parameter for a command, the 
system applies temporary defaults to the file specifications in the list. The 
following section describes how the system handles temporary defaults in file 
specification lists. 
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2.3.2 Temporary Defaults 

All DCL commands that accept lists of input files apply temporary defaults 
when you enter a command string that contains more than one input file 
specification. That is, if you do not give a complete file specification for each 
file in the list, the system will apply defaults taken from previous files in the 
list. 

The system applies temporary defaults to node names, device names, 
directory names, file names, and file types. If an input file specification 
explicitly includes a node, device and/or directory name, these names become 
the temporary defaults for the interpretation of subsequent file specifications 
within the list. 

File names and file types can also be defaulted, depending on the command 
you use. 

For example, assume that the current default device and directory name are 
USE1:[MONROE]. The following example shows how temporary defaults 
are applied to a list of file specifications that are parameters in a PRINT 
command. 

$ PRINT WRKD: [ADAMS]TEST1.DAT, - 
_$ TEST2, - 

_$ [JACKSON]SUMMARY.TST, - 
_$ USE1:FINAL 

The above PRINT command prints the files: 

WRKD:[ADAMS]TEST1.DAT 
WRKD:[ADAMS]TEST2.DAT 
WRKD:[JACKSON]SUMMARY.TST 
USE1:[JACKSON]FINAL.TST 

To substitute your current default directory for a temporary default, specify 
the directory as brackets with no directory name. For example, if your current 
default directory is [BETA], you can issue the following command: 

$ PRINT [ALPHA]TEST.DAT,[]FINAL 

The system will interpret the second file specification as [BETAJFINAL.DAT. 
The empty brackets indicate your current default directory, and the file type 
DAT is defaulted from the first file in the list. 


2.4 Rules for Entering Qualifiers 

The following sections explain the rules for entering qualifiers in DCL 
command strings. 


2.4.1 Types of Qualifiers 

There are three types of qualifiers: 

• Command qualifiers, which have the same meaning, regardless of where 
the qualifier appears in the command string 

• Positional qualifiers, which have different meanings depending on the 
qualifier's position in the command string 

• Parameter qualifiers, which can be used only after a specified type of 
parameter 
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Command qualifiers have the same meaning, whether they follow the 
command verb or a parameter. For example: 

$ PRINT/HOLD SPRING.SUM,FALL.SUM 
$ PRINT SPRING.SUM,FALL.SUM/HOLD 

The /HOLD qualifier is a command qualifier; therefore, the two PRINT 
commands shown above are equivalent. Both files are placed in a hold state. 

Positional qualifiers, however, have different meanings depending on where 
you place them in the command string. If you place a positional qualifier 
after the command verb but before the first parameter, the qualifier affects the 
entire command string. If you place a pos ional qualifier after a parameter, 
the qualifier affects only that parameter. 

For example: 

$ PRINT/C0PIES=2 SPRING.SUM.FALL.SUM 
$ PRINT SPRING.SUM/C0PIES=2,FALL.SUM 

The first PRINT command shown above requests two copies of each of the 
files SPRING.SUM and FALL.SUM. The second PRINT command requests 
two copies of the file SPRING.SUM, but only one copy of FALL.SUM. 

A parameter qualifier can be applied only to the specification of a parameter 
and cannot be specified following the command name. For example, the 
BACKUP command accepts several types of parameter qualifiers. 

The command descriptions in the VAX/VMS DCL Dictionary show the names 
and types of all qualifiers that can be used with each command. 


2.4.2 Qualifier Defaults 

A qualifier default is defined as what happens if you omit the qualifier 
from the command string. Qualifiers can be either present or absent by 
default. The format block in the command descriptions in the VAX/VMS DCL 
Dictionary lists the default action for each qualifier. 

The following paragraphs explain the syntax used in the VAX/VMS DCL 
Dictionary to display qualifiers and defaults. The following types of qualifiers 
are described: 

• Qualifiers with positive and negative forms 

• Qualifiers that require values 

• Qualifiers that accept optional values 

• Qualifiers that override other qualifiers 

• Qualifiers that affect command execution only if explicitly present 

The following example shows how the command descriptions in the 
VAX/VMS DCL Dictionary list a qualifier with a positive and negative form. 
The default action is shown on the right. 

/[NO]DELETE /NODELETE 

The /DELETE qualifier can be expressed positively or negatively. If you omit 
the qualifier, the default action is /NODELETE. 
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The next example shows a qualifier which requires a value. The default action 
is shown on the right. 

/COPIES=n /COPIES=1 

If you omit the /COPIES qualifier, the default is /COPIES=l. If you use the 
/COPIES qualifier, you must provide a value. 

The following example shows a qualifier that accepts an optional file 
specification value. 

/[NO]OBJECT[=file-spec] /NOOBJECT 

If you omit the /OBJECT qualifier, the default is /NOOBJECT. If you use the 
/OBJECT qualifier, the file specification is optional. The default shown above 
refers to the action taken when you omit the entire /OBJECT qualifier, not 
just the optional part of it. 

Note: Qualifiers that request output files accept file specification values and 
apply defaults for these specifications in a special way, as described in 
Section 2.4.4. 

The following example shows a qualifier that overrides another qualifier. The 
default action is shown on the right. 


Qualifier 

Default 

/EXECUTIVE-MODE 

/SUPERVISOR-MODE 

/SUPERVISOR-MODE 

/SUPERVISOR-MODE 

/USER_MODE 

/SUPERVISOR_MODE 


If you do not specify any of the /EXECUTIVE _MODE, /SUPERVISOR¬ 
MODE, or /USER_MODE qualifiers, the default is /SUPERVISOR-MODE. 
See the description of the DEFINE command in the VAX/VMS DCL Dictionary 
for examples of qualifiers that override other qualifiers. 

The following example shows the syntax for a qualifier that affects command 
execution only if explicitly present. Therefore, there is no corresponding 
default. For example: 

/ABORT None. 

The /ABORT qualifier does not affect the command if it is not specified. 

If you specify the same qualifier more than once when you enter a command, 
specify both a positive and negative form of the same qualifier, or specify 
a qualifier that overrides another qualifier, the command interpreter accepts 
only the last specification. For example: 

$ PRINT MYFILE /C0PIES=3/BURST/C0PIES*2/N0BURST 

For this PRINT command, the command accepts only the /COPIES=2 and 
the /NOBURST qualifiers. 

Note, however, that you can use positional qualifiers after more than one 
parameter in the command string. For example: 

$ PRINT/C0PIES=1 A.DAT/C0PIES=2, B.DAT/C0PIES=3 . C.DAT 
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In this example, two copies of the file A.DAT are printed, three copies of the 
file B.DAT are printed, and one copy of the file C.DAT is printed. Therefore, 
for the file A.DAT, the qualifier /COPIES=2 overrides /COPIES=l. For 
the file B.DAT, the qualifier /COPIES=3 overrides /COPIES=l. For the file 
C.DAT, the /COPIES=l qualifier applies. 

Some commands contain conflicting qualifiers that cannot be specified in 
the same command string. The command descriptions in the VAX/VMS 
DCL Dictionary indicate if qualifiers cannot be used together. The command 
interpreter usually issues an error message if you use incompatible qualifiers. 


2.4.3 Qualifiers That Accept Values 

Qualifiers can accept the following types of values: 

• Keywords 

• File specifications 

• Character strings 

• Numeric values 

The command descriptions in the VAX/VMS DCL Dictionary show whether a 
qualifier accepts a value, and indicate whether the value must be a keyword, 
a file specification, a character string, or a numeric value. 

When you enter a value for a qualifier, you must separate the qualifier and 
the value with either an equal sign ( = ) or a colon (:). For example, the 
following expressions are equivalent: 

/OUTPUT=DBA 1 :NEW.DAT /OUTPUT:DBA 1 :NEW.DAT 

/COPIES=3 /COPIES:3 

/OVERRIDE=EXPIRATION /OVERRIDE:EXPIRATION 

Some qualifier keyword values require additional data. In these cases, you 
must also separate the keyword from its data with a colon or an equal sign. 
For example, the following expressions are equivalent: 

/PROTECTION=GROUP:RW 

/PROTECTION:GROUP:RW 

/PROTECTION=GROUP=RW 

/PROTECTION:GROUP=RW 
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The command descriptions in the VAX/VMS DCL Dictionary use the following 
notation to indicate that a qualifier can accept a value or a list of values: 

/qualifier=(value[, . . . ]) The qualifier requires a value or list 

of values. If you specify a single 
value, you can omit the parentheses. 
However, if you specify a list of 
values, you must separate the values 
with commas and enclose them in 
parentheses. For example: 

$ SET COMMAND/DELETE=TYPE 
$ SET COMMAND/DELETE*(PRINT,COPY) 

/qualifier[=(value[, . . . ])] The qualifier accepts an optional value 

or list of values. If you specify a single 
value, you can omit the parentheses. 
However, if you specify a list of 
values, you must separate the values 
with commas and enclose them in 
parentheses. For example: 

$ RUNOFF/MESSAGES=USER 
$ RUNOFF/MESSAGES=(OUTPUT.USER) 


To specify multiple keywords that require values, enclose the list in 
parentheses and separate the keyword and value with either an equal sign 
( = ) or colon (:). For example: 

/BLOCKS=(START :0,END: 10) 
/PROTECTION=(OWNER=RWD,GROUP=RW) 


When you enter values for qualifiers, follow the rules for specifying these 
values in DCL command strings. For example, if a qualifier accepts a keyword 
value, you can abbreviate the keyword as described in Section 2.2.3.2. 


2.4.4 Qualifiers That Create Output Files 

Some qualifiers create output from a command and optionally accept a file 
specification for the output file name. The /LIST and /OBJECT qualifiers for 
the language compilers and the /EXECUTABLE qualifier for the linker are 
qualifiers that fit into this category. 

The default file specification for output files created by these qualifiers 
depends on the placement of the qualifier in the command. The rules are 
as follows: 

1 If the qualifier is present by default, the output file specification defaults 
to the current default device and directory, and the name of the first 
input file. The qualifier provides a default file type. Following are some 
examples. 
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Command 

Output File 

LINK A 

A.EXE 

LINK A,B 

A.EXE 

LINK [TEST]A,[ ]B 

A.EXE 

LINK A.OBJ 

A.EXE 


In these examples, the qualifier /EXECUTABLE is present by default. 
Therefore, the output file is named A.EXE and is written to the current 
default device and directory. The file type EXE is the default provided by 
the /EXECUTABLE qualifier. 

2 If the qualifier is used after the command name, and if the qualifier 
does not include an output file specification, the output file specification 
defaults to the current default device and directory, and the name of the 
first input file. The qualifier provides a default file type. Following are 
some examples: 


Command 

Output File 

LINK/EXECUTABLE A 

A.EXE 

LINK/EXECUTABLE A,B 

A.EXE 


3 If the qualifier is used after an input file specification and if the qualifier 
does not include an output file specification, the output file specification 
defaults to the device, directory, and file name of the immediately 
preceding input file. The qualifier provides a default file type. Following 
are some examples: 


Command 

Output Files 

MACRO A,B/LIST 

A.OBJ, B.OBJ, and B.LIS 

MACRO A+C/LIST 

A.OBJ and C.LIS 

LINK A+[TEST]D/EXE 

[TESTJD.EXE 


In the first example, the qualifier /OBJ is present by default, so the 
MACRO command produces the output files A.OBJ and B.OBJ. The 
qualifier /LIST is a positional qualifier which is not present by default. 
Therefore, it affects only the files after which it is specified. In this 
example, MACRO creates a listing file for B.MAR, named B.LIS. No listing 
is created for A.MAR. 

In the second example, the plus sign ( + ) concatenates the files A.MAR 
and C.MAR. The /OBJECT qualifier is present by default, so MACRO 
creates an object module with the same file name as the first input file. 
The /LIST qualifier is specified after the second file name, causing the 
listing to be named C.LIS. 

In the third example, the LINK command links two object files together. 
Because the qualifier /EXE is specified after the second input file, the 
resulting output file is named [TESTjD.EXE. This overrides the default 
output file naming convention. 

If the current process default device or directory is different from that 
specified for a command parameter, and if the output qualifier does not 
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include a specification, the output file resulting from the qualifier takes its 
device and directory from the command parameter. For example: 

$SH0W DEFAULT 
DISKI:[JONES] 

$MACRO [.PROGRAMS]A,B/LIST 

In this example, A.OBJ and B.OBJ are put in DISKl:[JONES]; however, 
B.LIS is put in DISKl:[JONES.PROGRAMS]. 

4 If the qualifier specifies a file specification for the output file, then any 
fields entered in the file specification are used to name the output file. 
Missing device and directory fields are filled in by the current process 
defaults. Following are some examples: 


Command 

Output File 

LINK A+B/EXE=C 

C.EXE 

MACRO/LIST=A B+C 

A.LIS and B.OBJ. Both files contain B and C 
concatenated. 

MACRO/LIST=A B,C 

B.OBJ, C.OBJ and 2 versions of A.LIS 

LINK/EXE=[TEST]A 

[TESTjA.EXE 


In the first example, A and B are linked together. The /EXE qualifier is 
used to override the default and name the output file C.EXE. 

In the second example, the /LIST qualifier is used to name the listing file 

A. LIS. The /OUTPUT qualifier is present by default so the object module 

B. OBJ is also produced. 

In the next example, the files B.MAR and C.MAR are assembled 
separately. The /OBJECT qualifier is present by default and creates 
B.OBJ and C.OBJ. The /LIST qualifier creates two versions of A.LIS, one 
for A and one for B. 

The last example shows how to use the /EXE qualifier to change the 
directory of an image created by the linker. 

In all cases, the version number of the output file is always one greater than 
any existing file with the same file name and file type. 

If the current process default device or directory is different from that 
specified in the command parameter, the current process default is used 
for the output file. For example: 

ISHOW DEFAULT 
DISKI:[JONES] 

IMACRO DISK2:[SMITH]A/LIS=B 

This example produces the output files DISKl:[JONES]A.OBJ and 
DISKI :[JONES]B.LIS. 

Note that when a logical name is used for any input file specification, the 
entire equivalence name of the logical name is used to determine the output 
file specification. If a logical name is used for an input file and its equivalence 
name contains a file type, then the same file type is used for the output file 
unless you specify a different file type. To avoid the confusion that can result 
from this situation, omit the file type from the file specification when you 
create the logical name for the input file. 
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2.5 Specifying Dates and Times 

Certain commands and qualifiers accept date and time values. You 
can specify these values in absolute time format, delta time format, or 
combination time format. The command descriptions in the VAX/VMS DCL 
Dictionary indicate the time formats accepted by commands and qualifiers. 


2.5.1 Absolute Time 


Absolute time is a specific date and/or time of day. The format for an 
absolute time is: 

[dd-mmm-yyyy[:]][hh:mm:ss.cc] 

The variable fields are as follows: 


Field Meaning 

dd Day of the month; an integer in the range of 1-31 

mmm Month; specified as JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, 

SEP, OCT, NOV, or DEC 

yyyy Year; an integer 

hh Hour of the day; an integer in the range of 0-23 

mm Minute of the hour; an integer in the range of 0-59 

ss Seconds; an integer in the range of 0-59 

cc Hundredths of a second; an integer in the range of 0-99 


You can specify an absolute time value using either the date or the time, or 
both. 

If you specify both the date (dd-mmm-yyyy) and the time (hh:mm:ss.cc), you 
must type the colon between the date and the time. You can also truncate 
either the date or the time on the right; however, the date field, if specified, 
must always contain at least one hyphen. 

You can omit any of the fields within the date or time, as long as you type the 
punctuation marks that separate the fields; the system supplies default values. 
If you omit a field from the date, the system supplies the corresponding field 
for the current date. If you omit a field from the time, the system supplies a 
default value of zero. 

You may also use one of the following keywords to specify an absolute time. 


Keyword Meaning 

TODAY The current day, month, and year at 00:00:00.0 o'clock 

TOMORROW 24 hours after 00:00:00.0 o'clock today 

YESTERDAY 24 hours before 00:00:00.0 o'clock today 

The following examples show absolute time specifications: 


2-13 











Syntax Rules for Entering DCL Commands 


2.5.2 


Time Specification 

Result 

15-APR-1985:12 

12:00 noon on April 15, 1985 

15-APR 

Midnight (00:00 o'clock) at the beginning of the 
15th of April, this year 

15 

3:00 P.M., today 

15- 

The 15th day of the current month and year, at 
midnight 

18:30 

6:30 P.M., today 

15—::30 

00:30 o'clock, on the 15th day of the current 
month 

00:00:00.2 

Two-hundredths of a second after midnight, today 


Note that whenever you issue a command and specify an absolute time that 
has already passed, the system executes the specified action immediately. 


Delta Time 

Delta time is an offset from the current time to a time in the future. The 
format for a delta time is: 

[dddd-][hh:mm:ss.cc] 

The variable fields are as follows: 


Field Meaning 

dddd Number of days; an integer in the range of 0-9999 

hh Number of hours; an integer in the range of 0-23 

mm Number of minutes; an integer in the range of 0-59 

ss Number of seconds; an integer in the range of 0-59 

cc Number of hundredths of seconds; an integer in the range of 0-99 


You can truncate a delta time on the right. You can also omit any of the 
fields, as long as you supply the punctuation marks between fields. Truncated 
or omitted fields default to zero. You can begin a delta time with either the 
day or the time field. If you begin with a day, you must include the hyphen 
(-)• 

The following examples show delta time specifications: 


Time Specification 

Result 

3- 

3 days from now (72 hours) 

3 

3 hours from now 

:30 

30 minutes from now 

3-:30 

3 days and 30 minutes from now 

15:30 

15 hours and 30 minutes from now 


Note: Do not use the delta time format in places where the command interpreter 
also accepts absolute or combination time formats. In these places you 
must use the combination time format to specify an offset from the 
current time. 
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2.5.3 


Combination Time 

Combination time consists of an absolute time value plus or minus a delta 
time value. The delta time portion of the combination time must always be 
preceded by a plus or minus sign. Whenever a plus sign precedes the delta 
time value, the entire time specification must be enclosed in quotation marks. 
However, if a minus sign is used, no quotes are needed. (Note that the minus 
sign is the same keyboard key as the hyphen.) 

When you specify a combination time, you can omit the absolute time. If 
you omit the absolute time value, the delta time is offset from the current 
date and time of day. If you specify any part of the absolute time, the 
defaults are those specified in the description of absolute time. However, 
it is recommended that you specify date-time information as completely as 
possible. 

The variable fields and default fields for absolute and delta time values are the 
same as those described in the preceding sections. The following examples 
show combination time specifications: 


Time Specification 

Result 

"+5" 

Current time plus 5 hours. The absolute time 
portion is omitted, so it defaults to the current 
date and time. 

"+:5" 

Current time plus 5 minutes. The absolute time 
portion is omitted, so it defaults to the current 
date and time. 

" 15-APR:+:5" 

12:05 AM on April 15 of the current year. The 
absolute time specification (before the colon) 
defaults to midnight on April 15 of the current 
year. The plus sign ( + ) indicates a positive offset. 

"TOMORROW* 1 -00:00" 

Tomorrow plus 1 day. 

-:5 

Current time minus 5 minutes. The absolute 
time specification is omitted, so it defaults to the 
current date and time. 

-1 

Current time minus 1 hour. The minus sign (-) 
indicates a negative offset. (The 1 is interpreted 
as an hour, not a day, because it is not followed 
by a dash.) 

-1-00 

Current time minus 1 day. The minus sign (-) 
indicates a negative offset. The dash (-) separates 
the day from the time field. 

15-APR:-00:10 

11:50 PM on April 14 of the current year. The 
absolute time specification before the colon (15- 
APR) defaults to midnight on April 15 of the 
current year. The minus sign (-) after APR: 
indicates a negative offset. The dash (-) indicates 
that the value for the day is missing. 
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2.6 Interrupting Execution of DCL Commands 

Most DCL commands are executed by calling images. Thus when you issue 
most commands, the command interpreter passes control to the image for the 
command. 

You can interrupt the execution of a DCL command by pressing CTRL/Y. 
When the image corresponding to the command is interrupted, control is 
returned to the command interpreter, and you will receive the DCL prompt. 

At the DCL prompt, you can either terminate the image or keep it in an 
interrupted state until you return to it. 

The DCL commands in Table 2-1 are performed as routines within the 
command interpreter; they do not cause a nonprivileged interrupted image to 
exit. Therefore, if you interrupt a command that calls a nonprivileged image, 
you can issue any of the commands in Table 2-1 without losing the context 
for your command. If you issue any other commands, or if you execute a 
command procedure, then the interrupted image is forced to exit. 

To return to an interrupted command, use the CONTINUE command as 
shown: 

$ DIRECTORY/FULL 


1 CTRL/Y | 

$ SHOW DEFAULT 
$ CONTINUE 


In this example, the DIRECTORY command is interrupted, the SHOW 
DEFAULT command is issued, and then the DIRECTORY command is 
resumed. 

If you interrupt a privileged image, you can issue only the SPAWN, ATTACH, 
and CONTINUE commands without causing the interrupted image to exit. 
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Table 2-1 Commands Performed Within the Command 
Interpreter 


= 

DEPOSIT 

SET OUTPUT_RATE 

ALLOCATE 

DISCONNECT 

SET PROMPT 

ASSIGN 

EOD 

SET PROTECTION/DEFAULT 

ATTACH 

EXAMINE 

SET SYMBOL 

CALL 

EXIT 

SET UIC 

CANCEL 

GOSUB 

SET VERIFY 

CLOSE 

GOTO 

SHOW DEFAULT 

CONNECT 

IF 

SHOW KEY 

CONTINUE 

INQUIRE 

SHOW PROTECTION 

CREATE/LOGICAI_ 

NAME_TABLE 

ON 

SHOW QUOTA 

DEALLOCATE 

OPEN 

SHOW STATUS 

DEASSIGN 

READ 

SHOW SYMBOL 

DEBUG 

RECALL 

SHOW TIME 

DECK 

RETURN 

SHOW TRANSLATION 

DEFINE 

SET CONTROL 

SPAWN 

DEFINE/KEY 

SET DEFAULT 

STOP 

DELETE/KEY 

SET KEY 

WAIT 

DELETE/SYMBOL 

SET ON 

WRITE 


After you interrupt a DCL command, you may want to execute a command 
that calls an image without losing the context of your interrupted image. You 
can do this by using the SPAWN command to create a subprocess. 

For example, you can interrupt the EDT Editor, SPAWN a subprocess, read 
your mail, return to your main process, and continue your editing session as 
shown in the following example. 

$ EDT WORKFILE.TXT 


| CTRL/Y | 

$ SPAWN 

y.DCL-S-SPAWNED, process J0NES_1 spawned 

XDCL-S-ATTACHED, terminal now attached to process J0NES_1 

$ MAIL 

MAIL> 


MAIL> EXIT 
$ LOGOUT 

Process JONES.l logged out at 15-APR-1985 17:03:04.03 
%DCL-S-RETURNED, control returned to process JONES 

$ CONTINU E 

| CTRL/W | 

After you resume your editing session with the CONTINUE command, use 
CTRL/W to refresh your screen if you are using character mode. 
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3 File Specifications 


A file is a logically related collection of records. To uniquely identify a file 
that you want to access, you use a file specification. 

When you specify a file that is stored on a mass storage device (such as a disk 
or a magnetic tape), you need to provide the file name and the name of the 
device that holds the media containing the file. For files on disks, you must 
also specify the directory where the file is cataloged. Some of this information 
can be provided using defaults, as discussed in Section 3.2. 

Although record-oriented devices (such as terminals and printers) cannot 
store files, sometimes they can be treated as files. For example, the COPY 
command copies data from one file to another. You can copy a file on a 
mass storage device to your terminal (a record-oriented device) by specifying 
the terminal's device name as the output file specification. Following is an 
example. 

$ COPY MYFILE.DAT TTB4: 

This command displays the file MYFILE.DAT on the terminal named TTB4. 
The terminal accepts, and displays, the file one record at a time. When you 
use a terminal or printer device name as a file specification, provide the device 
name followed by a colon. 

This chapter provides the rules for using VAX/VMS file specifications and 
device names with DCL commands. It contains information on: 

• Specifying the parts of a file specification, including the file name, type, 
directory, device, and node 

• Using wildcards in file specifications to indicate groups of files 


3.1 Format for File Specifications 

A file specification provides the system with all the information it needs to 
identify a file. 

A full file specification has the following format: 

node::device:[root.][directory]filename.type;version 

Punctuation marks and brackets are required to separate the fields of the file 
specification. The fields are as follows: 


Field Contents 


node 

Network node specification 

device 

Device name 

directory 

Directory name or list 

filename 

File name 

type 

File type 

version 

File version number 
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The maximum size of a file specification, including all delimiters, is 255 
characters. 

The following example illustrates the format of a file specification. 

BOSTON::DISK1:[LICENSES]SUMMER_1984.DAT;18 
I II I II 

node device directory filename type version 

The fields for file name, type, and version apply only to files on mass storage 
devices. The directory field applies only to files on disks. The node is used 
only if your system is part of a network. 

For record-oriented devices, use only the device field in the file specification. 


3.2 Defaults for File Specifications 

When you enter a file specification, you can omit fields in the specification 
and let the system supply default values for these fields. Table 3-1 gives a 
summary of the defaults applied to each field in a file specification. 

Note that the system supplies the defaults described in Table 3-1 for the first 
input file specification that you enter on a DCL command line. However, 
when you enter more than one input file specification, the system applies 
temporary defaults, as described in Section 2.3.2. 


Table 3-1 File Specification Defaults 


Field 

Defaults 

node 

The system assumes that the device is on the local system. 

device 

The system uses the device (usually a disk) established 
at login or by the SET DEFAULT command. Devices are 
usually identified by using logical names. 


If a physical device name is used and a controller 
designation is omitted, the controller designation defaults 
to A. If a unit number is omitted, the unit number defaults 
to 0. (The ALLOCATE, MOUNT, and SHOW DEVICES 
commands, however, treat a device name that does not 
contain controller and/or unit numbers as a generic device 
name.) For more details, see the discussions of these 
commands in the VAX/VMS DCL Dictionary. 

directory 

The system uses the directory name established at login or 
by the SET DEFAULT command. 

file name 

No defaults are applied to the first file name in an input 
file specification. Most commands apply default output file 
names based on the file name of an input file. 

file type 

Various commands apply defaults for file types, based 
on the standard file type conventions summarized in 

Table 3-2. 

file version 

For input files, the system assumes the highest version 
number. 


For output files, if no file with the specified file name and 
file type exists in the current directory, the file is created 
with a version number of 1. However, if one or more 
versions do exist, the next highest version number is used. 
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3.3 File Names, File Types, and Version Numbers 

File names, file types, and version numbers identify files on mass-storage 
devices. 

A file name is a 1- through 39-character string that provides a name for a file. 
When you create a file, you can assign it a file name that is meaningful to 
you. 

A file type is a 1- through 39-character string that usually identifies the file in 
terms of its contents. File types must be preceded with a period. 

You can use the following characters in file names and file types: 

• A through Z 

• a through z 

• 0 through 9 

• Underscore 

• Hyphen 

• Dollar sign (reserved for special use by DIGITAL) 

All alphabetic characters in file names and types are interpreted as uppercase. 
Also, file names and types cannot begin with the dollar sign, hyphen, or 
underscore characters. Since directories are files, directories also cannot begin 
with the dollar sign, hyphen, or underscore characters. 

By convention, the VAX/VMS operating system uses a set of standard file 
types to identify various classifications of files and to provide default file 
types in many commands. Table 3-2 lists default file types used by DCL 
commands. 

Version numbers are decimal numbers from 1 to 32,767 that differentiate 
versions of a file. When you update or modify a file and do not specify a 
version number for the output file, the system saves the original version 
for backup and increments the version number by 1 for the output file. 

The /VERSION-LIMIT qualifier on the CREATE/DIRECTORY, SET 
DIRECTORY, and SET FILE commands allow you to limit this number 
further. 

Version numbers must be preceded with a semicolon or a period. When the 
system displays file specifications, it generally displays a semicolon in front of 
the file version number. 

You can refer to versions of a file in a relative manner by specifying a zero or 
a negative version number in the file specification. Specifying a zero version 
number locates the latest (highest numbered) version of the file. Specifying 
-1 locates the next-most-recent version, -2 the version before that, and so on. 


Table 3-2 Default File Types 

File Type Contents 

ANL Output file for the ANALYZE command 

BJL BACKUP journal file 

CLD Command description file 
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Table 3-2 (Cont.) Default File Types 

File Type Contents 


COM 

DAT 

DIF 

DIR 

DIS 

DMP 

EDT 

EXE 

FDL 

HLB 

HLP 

INI 

JNL 

JOU 

LIS 

LOG 

MAI 

MAP 

MAR 

MEM 

MLB 

MSG 

OBJ 

OLB 

OPT 

PAR 

RNO 

STB 

SYS 

TEC 

TJL 

TLB 

TMP 

TPU 

TXT 

UPD 


Command procedure file to be executed with the @ (Execute 
Procedure) command, or to be submitted for batch execution 
with the SUBMIT command 

Input or output data file 

Output listing created by the DIFFERENCES command 
Directory file 

Distribution list file for the MAIL command 

Output listing created by the DUMP command 

Initialization command input file for the EDT Editor 

Image file created by the linker 

File definition language file 

Help text library file 

Input source file for help libraries 

Initialization file 

Journal file created by the VAX/VMS PATCH Utility 
Journal file created by the EDT Editor 

Listing file created by a language compiler or assembler; default 
input file type for PRINT and TYPE commands 

Batch job output file 
Mail message file 

Memory allocation map created by the Linker 
Input source file for the VAX MACRO assembler 
Output file for DIGITAL Standard Runoff 
Macro library for the VAX MACRO assembler 
Source file that specifies the text of messages 
Object file created by a language compiler or assembler 
Object module library 

Options file for input to the LINK command 
SYSGEN parameter file 

Input source file for DIGITAL Standard Runoff 
Symbol table file created by the linker 
System image 
TECO indirect command file 

Journal file created by the VAXTPU and ACL editors 
Text library 
Temporary file 

Command file for the VAXTPU Editor 

Input file for text libraries or MAIL command output 

Update file of changes for a VAX-11 MACRO source program; 
also input to the SUMSLP Editor 
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3.3.1 Null File Names and File Types 

The file name and file type fields of a file specification can be null. For 
example, the following are valid file specifications: 

.TMP (file name is null) 

TEMP. (file type is null) 

When you specify a file in a DCL command, you must be careful to omit 
the period following a file name if the command uses a default file type. 
For example, the FORTRAN command uses a default file type of FOR. The 
following commands produce different results: 

$ FORTRAN TEMP 
$ FORTRAN TEMP. 

In the first example, the FORTRAN compiler looks for a file named 
TEMP.FOR because the file type was omitted. In the second example, the 
compiler looks for a file named TEMP, because a period following the file 
name explicitly specifies the null file type. 


3.3.2 Alternate File Names for Magnetic Tapes 

In addition to standard file names, the VAX/VMS operating system supports 
an alternate file naming convention for ANSI-labeled magnetic tapes. This 
file name consists of up to 17 ASCII "a" characters. These characters include 
alphanumeric characters and a set of special characters, that include the 
following: 

SP ! % k 


3.4 Directories 


A directory is a file that catalogs (by name and location) a set of files on a 
disk volume set. Directories apply only to files on disk devices. A directory 
file contains the following information for every file cataloged in the directory: 

• The file name, type, and version number 

• A pointer to the file header, which describes the file (including owner, 
protection, attributes, and location on the disk) 

You must have a top-level directory, provided by the system manager, before 
you can create and store files on disks. A directory file has a file type of DIR. 


3.4.1 Default Directories 

When you log in to the system, your default directory is your top-level 
directory, established by the system manager. To change your default 
directory, use the SET DEFAULT command. 

You can determine your current default disk and directory name by issuing 
the SHOW DEFAULT command. For example: 

$ SHOW DEFAULT 

USE1:[RABBIT] 

The system's response indicates that the current default disk is USE1 and 
the default directory name is [RABBIT]. You can change the disk and 
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directory defaults during a terminal session or in a batch job by using the SET 
DEFAULT command. For example, the following SET DEFAULT command 
would change the default directory to [PUBLIC]: 

$ SET DEFAULT [PUBLIC] 


3.4.2 How Directories Are Structured on a Disk Volume 

Every volume contains a master file directory (MFD). An MFD is a directory 
that contains a list of all user file directories (UFDs) for the volume, with 
pointers to each UFD. 

A user file directory (UFD) lists the names of files cataloged in the user's 
directory, and has information pointing to each cataloged file. In addition to 
data files, a user file directory can contain directory files, called subdirectories. 
A subdirectory contains names and pointers for files cataloged in the 
subdirectory. 

Figure 3-1 shows how directories are structured on a disk volume. In this 
figure, the MFD is [000000]. The MFD contains entries for user file directories 
(UFDs) including: MALCOLM.DIR, 301300.DIR, and HIGGINS.DIR. Each 
entry in the MFD points to the corresponding UFD. Each UFD has entries for 
the user's files cataloged in that directory. 

The directory file HIGGINS.DIR is the user file directory for HIGGINS. 

This is HIGGINS' default directory when he logs in. Although the name 
of the directory file is HIGGINS.DIR, the directory name (as given in file 
specifications) is [HIGGINS]. (The directory name is the portion of the 
directory file name before the file type DIR. Enclose the directory name in 
brackets when you use it in a file specification.) 

The directory file HIGGINS.DIR contains entries that point to the files in 
HIGGINS' top-level directory. The command: 

$ DIRECTORY [HIGGINS] 

displays the names of the files in the [HIGGINS] directory. 

Two of the files cataloged in the [HIGGINS] directory point to data files; the 
third (PAYROLL.DIR) points to another directory file called a subdirectory. A 
subdirectory can contain an entry for another subdirectory; that subdirectory 
can contain an entry for another subdirectory, and so on up to seven levels of 
subdirectories. This structure (a top-level directory plus a maximum of seven 
levels of subdirectories) is called a directory hierarchy. 

You can use the DIRECTORY command to list the files cataloged in a 
subdirectory. For example, the file [HIGGINSJPAYROLL.DIR catalogs files in 
the subdirectory [HIGGINS.PAYROLL]. The command: 

$ DIRECTORY [HIGGINS.PAYROLL] 

displays the files in the [HIGGINS.PAYROLL] directory. As shown in 
Figure 3-1, the subdirectory [HIGGINS.PAYROLL] contains entries for a 
data file and a subdirectory. 
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Figure 3—1 How Directories Are Structured on a Disk Volume 
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3.4.3 Directory Names 

Directory names have two possible formats: 

• Named format 

• UIC format 

A named directory consists of a top-level directory name or a top-level 
directory name followed by a maximum of seven subdirectory names. Each 
name can be 1 through 39 alphanumeric characters long, and can contain any 
characters that are allowed in file names. A UlC-format directory contains a 
two-part octal number that forms a user identification code (UIC). 

Both formats require the directory name to be enclosed in either square 
brackets ([]) or angle brackets ( < > ). 

A top-level directory name can be any character string that you request or 
that the system manager gives you. The following example shows a top-level 
directory name: 

[MALCOLM] 

To specify a sequence of directory and subdirectory names, separate each 
name with a period. For example: 

[MALCOLM.TESTFILES] 

[GROUP122.TESTFILES.DATA] 

The subdirectory [MALCOLM.TESTFILES] is a subdirectory that is 
cataloged in the [MALCOLM] top-level directory. The subdirectory 
[GROUP122.TESTFILES.DATA] is cataloged in the subdirectory 
[GROUP122.TESTFILES]; the subdirectory [GROUP122.TESTFILES] is in turn 
cataloged in the top-level directory [GROUP122]. (The top level directories 
[MALCOLM] and [GROUP122] are both cataloged in the MFD.) 

If you specify a directory name that starts with a period, the system places 
your current default directory before the period. For example, if your current 
default directory is [MALCOLM.TESTFILES] and you issue the command: 

$ TYPE [.SUB]FILE.DAT 

the file [MALCOLM.TESTFILES.SUB]FILE.DAT is displayed. 

You can also specify a directory name that starts with a hyphen (-). 

This allows you to move up one level in the directory hierarchy for each 
hyphen you specify. For example, if your current default directory is 
[MALCOLM.TESTFILES.SUB], the following command displays the file 
[MALCOLM.TESTFILES.DATAJTEST.DAT: 

$ TYPE [-.DATA]TEST.DAT 

A directory name in UIC format contains a group number and a member 
number, separated by a comma. The group number and the member number 
can each contain up to three octal digits. For example: 

[122.1] 

Directory names in UIC format generally, but not necessarily, correspond to 
the UIC of the owner of the directory. You must use UIC format directories 
on volumes that will be transported to RSX-11 systems. 
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To use the named format to specify directories whose names are in UIC 
format, zero-fill the group and member fields on the left (if necessary). For 
example: 

[122001] 

This directory specification is equivalent to the specification [122,1] in the 
preceding example. 

A directory name may not mix UIC format and named format. For 
example, [122,1.SUB] is invalid. If you have a directory with a name in 
UIC format, you must specify it in named format when you are specifying its 
subdirectories. For example, [122001.SUB] would be valid. 


3.4.4 Creating Subdirectories 

You can create a hierarchy of subdirectories from your top-level directory to 
organize your files into related categories. To create a subdirectory, use the 
CREATE/DIRECTORY command followed by the name of the subdirectory 
you are creating. The subdirectory name contains the name of the directory 
where the subdirectory is cataloged, followed by the name of the new 
subdirectory. Separate the directory and subdirectory names with a period 
(.). For example, a subdirectory in the top-level directory [MALCOLM] could 
be named [MALCOLM.SUB]. 

To create the subdirectory [MALCOLM.SUB], issue the command: 

$ CREATE/DIRECTORY [MALCOLM.SUB] 

This command places an entry for the directory file SUB.DIR into the top 
level directory [MALCOLM]. The entry for SUB.DIR points to the directory 
file which catalogs files in the subdirectory [MALCOLM.SUB]. For example, 
if you create a file [MALCOLM.SUBJNEWFILE.DAT, it will be cataloged in 
[MALCOLM.SUB]. 

You cannot edit a directory file. Therefore, all directory files have a version 
number of 1. 


3.4.5 Deleting Directories 

Use the DELETE command to delete a directory file. Note that you can delete 
a directory only when it is empty. In order to delete a directory, you must 
either remove or delete all the files listed in it. When the directory is empty, 
you can delete the directory file. In most cases, you will need to change the 
protection of the directory file before you can delete it. 

For example, suppose you want to delete the directory [MALCOLM.SUB] 
which you own. First, delete all the files cataloged in [MALCOLM.SUB]. 
Next, you need to delete the file SUB.DIR from the [MALCOLM] directory. 
(In order to delete the subdirectory [MALCOLM.SUB], you must delete the 
entry in the [MALCOLM] directory which points to the subdirectory.) Before 
you can delete the file SUB.DIR, you must change its file protection so you 
(the owner) can delete it: 

$ SET PROTECTION 3 (0:RWED) [MALCOLM]SUB.DIR 

Next, delete the directory file as shown below: 

$ DELETE [MALCOLM]SUB.DIR; 
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3.5 Devices 


Devices are classified as either mass storage or record oriented. 

Mass storage devices provide a way to save the contents of files on a magnetic 
medium. Files that are saved can then be accessed at any time and updated, 
modified, or reused. Disks and magnetic tapes are mass storage devices. 
When disk packs or reels of magnetic tape are mounted on drives, they are 
called volumes. 

Record-oriented devices read and write only single physical units of data at 
a time, and do not provide online storage of the data. Terminals, printers, 
mailboxes, and card readers are record-oriented devices. (Printers and card 
readers are also called unit record devices.) 

You can use physical, logical, or generic names to refer to devices. These 
types of device names are described in the following sections. In addition, if 
your system is part of a cluster, certain devices are accessible to all members 
of the cluster. Section 3.5.4 describes the syntax for cluster device names. 

Note that certain commands such as ALLOCATE and MOUNT require that 
you specify a device name. When a command requires a device name, specify 
only the device portion of the file specification. 


3.5.1 Physical Device Names 

Each physical device known to the system is uniquely identified by a physical 
device name specification in the following format: 

ddcu 

In this example dd is a code for the device type, c is a controller designation, 
and u is a unit number. 

Table 3-3 lists the valid device types and their codes. 

The controller designation and unit number identify the location of the device 
within the hardware configuration of the system. Controllers are designated 
with alphabetic letters A through Z. Unit numbers are decimal numbers from 
0 through 65,535. 

The maximum length of the device name field, including the controller and 
the unit number, is 15 characters. When you specify a device name as part of 
a file specification, terminate it with a colon (:). 


Table 3-3 Device Types 


Code 

Device Type 

CR 

Card reader 

CS 

Console storage device 

DA 

RC25 cartridge disk 

DB 

RP05, RP06 disk 

DD 

TU58 cartridge tape 

DJ 

RA60 Disk 

DL 

RL02 cartridge disk 
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Table 3-3 (Cont.) Device Types 

Code Device Type 

DM RK06, RK07 cartridge disk 

DQ RL02 cartridge disk, R80 disk (730 IDC only) 

DR RM03, RM05, RM80, RP07 disk 

DU RA80, RA81 disk 

DX RX01 floppy diskette 

DY RX02 floppy diskette 

LA LPA11-K laboratory peripheral accelerator 

LC Line printer on DMF32 

LP Line printer on LP11 

LT Local area terminal 

MB Mailbox 

MF TU78 magnetic tape 

MS TS11 magnetic tape 

MT TE16, TU45, TU77 magnetic tape 

MU TA78, TA81, TK50, TU81 magnetic tape 

NET Network communications logical device 

NL System "null" device 

OP Operator's console 

RT Remote terminal 

TT Interactive terminal 

TX Interactive terminal 

VT Virtual terminal 

XA DR11 —W general purpose DMA interface 

XD DMP-11 synchronous communications line 

XE DEUNA synchronous communications line 

XF DR32 interface adapter 

XG DMF32 synchronous communications line 

XJ DUP11 synchronous communications line 

XM DMC11 synchronous communications line 

XQ DEQNA synchronous communications line 


When you refer to a file on a disk volume set, you can specify either the 
name of the device on which the first volume in the set is mounted or the 
logical name assigned to the volume set when it was mounted. If you do not 
specify a logical or physical device name, your current default device name is 
supplied. 
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3.5.2 Logical Device Names 

Your system manager can set up logical names to indicate the devices 
available to you. (Chapter 4 describes logical names.) You should use these 
logical names, rather than the physical device names, when referring to files. 
In doing this, you can achieve file and device independence. When you use a 
logical device name in a file specification, you must terminate the name with 
a colon. 

If you specify a file using a logical device name, you can access the file 
regardless of which physical device holds the disk or tape containing your 
file. Your system manager will ensure that the logical device names are 
always equated to the correct physical devices. 

For example, the file specification 

USEl:[NOAH]ANIMALS.LIS 

uses a logical device name to specify the device containing the disk volume 
with the file [NOAHJANIMALS.LIS. As long as the system manager defines 
the logical name USEl correctly, the system can access your files, regardless 
of where the volume is mounted. 

The VAX/VMS operating system offers a special type of logical device name 
called a concealed device name. If a device has a concealed device name, 
the logical name (not the physical device name) will be displayed in system 
messages that refer to the device. See Chapter 4 for more information on 
concealed device names. 


3.5.3 Generic Device Names 

Some commands allow you to specify a generic device name. Such a device 
name is one in which the controller and/or the unit number is not specified. 
When you use a generic device name, the system locates an available device 
unit whose physical name satisfies the portions of the generic device name 
that are specified. For example, if you issue an ALLOCATE command and 
specify only a device type, the ALLOCATE command locates an available 
unit of that type. 

For all commands except ALLOCATE and MOUNT, if you omit the controller 
designation, it is assumed to be A; if you omit the unit number, it becomes 0. 
When you omit the controller or unit number in an ALLOCATE or MOUNT 
command, the device is treated as a generic device name as just described. 


3.5.4 Cluster Device Names 

A cluster device name has the following format: 

cluster-node$device-name 

Cluster-node is the name of the node to which the device is attached. Device¬ 
name is the physical device name of the device, in the format: 

ddcu 

Physical device names are described in Section 3.5.1. 
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If a device is dual pathed, you should specify the cluster device name in the 
following format: 

$allocation-class$device-nanie 

For more information on cluster device names, see the Guide to VAXclusters. 


3.6 Network Nodes 

If your system is part of a network, a node name may be included in a file 
specification to specify a file on a remote node. A node is an individual 
system that is part of a computer network. The node that you access when 
you log in is your local node; other nodes in the network are remote nodes. 
When you access files using DECnet-VAX, DECnet-VAX logs in at the remote 
node to perform the requested operation. 

A node name can contain 1 to 6 alphanumeric characters and must contain 
at least one alphabetic character. A node name must always be followed 
by a double colon (::). The following example identifies a file on the node 
BOSTON. 

BOSTON::USE1:[MILLS]MEMO.DAT 

When you specify a node name, you can optionally include a 0 to 42- 
character access control string to specify login information to be sent to the 
remote node. The access control string designates an account you can log in 
to on the remote node. 

If you omit the access control string, the login information sent to the remote 
node is determined as follows. If a proxy login account exists for you on the 
remote node, then the system logs you in using that account. (A proxy login 
account allows selected users to log in to a node.) If a proxy login does not 
exist, then the system logs you in using the default DECnet account for that 
node as specified by the local system manager. 

A node name with an access control string has the following format: 

node"acce88-control-string ,, : : 

You must enclose the access control string in quotation marks and place 
the double colon after the access control string, as shown in the previous 
example. 

For VAX/VMS systems, the access control string consists of a user name, 
followed by one or more spaces or tabs and a password as shown in this 
example. 

BOSTON"HIGGINS HENRY":: 

Here, BOSTON is the network node name, HIGGINS is a user name on 
BOSTON, and HENRY is the password associated with that name. When you 
access a file on the remote node BOSTON, DECnet-VAX will log in to the 
remote node using the HIGGINS login information. The remainder of the file 
specification is passed to the remote node and is interpreted there. 

If you include the name of a local node as part of a file specification, DECnet- 
VAX will access the file over the network in the same way it would access a 
file on a remote node. That is, DECnet-VAX will log in over the network and 
perform the file operation, even though the file exists on your local node. 

There are three forms of network file specification. In each form, the node 
specification can optionally include an access control string. 
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node:: device: [directoryjfilename. type; version 
node: :"foreign-file-spec-string" 
node::"task-spec-string" 

The first format is the conventional format for VAX/VMS files. 

The second format is used to provide a foreign file specification. (A foreign 
file specification is a file that does not conform to the VAX/VMS syntax.) For 
example: 

BOSTON::"TEST7.DAT" 

The file name in the above example contains a question mark ("?") character. 
Therefore, the file specification must be enclosed in quotes. The foreign file 
specification must be in a format that is recognized by the operating system 
of the remote node you are accessing. 

The third format specifies a task specification string. Such a string identifies a 
program to be executed on the remote node. For example: 

BOSTON::"TASK-TEST2" 

The above specification identifies the program TEST2 on the remote node 
BOSTON. Usually, task specification strings are used within a program to 
enable it to communicate with another program on a remote node. 

A special type of logical name, a logical node name, may be used in place of 
the node name. See Chapter 4 for information on logical node names. 


3.7 Using Wildcard Characters in File Specifications 

You can use wildcard characters in file specifications to refer to a group of 
files by a general name, rather than specifying each file individually. DCL 
provides two general purpose "wildcard" characters: 

• Asterisk (*) 

• Percent sign (%) 

These general purpose wildcards can be used in directory names, file names, 
and file types. The asterisk can be used in the version number field. The 
percent sign is not supported for use in the version number field, or for use in 
the 17-character ANSI magnetic tape file specifications. 

In addition to the two general purpose wildcard characters, there are two 
special directory-searching wildcard characters that can be used only in 
directory specification fields: 

• Ellipsis (...) 

• Hyphen ( -) (also called "minus sign") 

You cannot use the directory-searching wildcards in directory specifications in 
UIC format. 

The following sections describe the general rules for using wildcard characters 
in input and output file specifications. Particular uses of wildcard characters 
in DCL commands vary with the individual commands. The command 
descriptions in the VAX/VMS DCL Dictionary indicate (in each place where a 
file specification is described) whether wildcard characters are allowed. When 
a command allows wildcard characters in parts of the file specification where 
wildcards are normally permitted, it is said to allow full wildcarding. 
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3.7.1 Using Wildcards in Input File Specifications 

The following sections describe how the four wildcard characters can be used 
in file specifications for input files. 


3.7.1.1 The Match-All Wildcard Character (Asterisk) 

Use the asterisk wildcard character when you want to process all file 
specifications that match a given value in a field or portion of a field. You 
can use the asterisk in the directory, file name, file type, and version fields, 
with the following exceptions: you cannot use the asterisk for a portion of 
the version field or for a portion of an ANSI tape 17-character file name. 

The number of characters that you can match with an asterisk ranges from 
zero to the maximum size of the field in which the asterisk appears. That is, 
if the field containing the asterisk permits 39 characters, as the file type does, 
matches occur on fields that are zero through 39 characters long. 

Consider some examples of the asterisk used in place of an entire field. 

The following file specification will select all versions of all files in the 
[MALCOLM] directory: 

$ PRINT [MALCOLM]*.*;* 

As shown in the above example, wildcard characters allow you to manipulate 
large numbers of files without naming them individually. 

A file specification such as the one used in the following example limits the 
files selected to a more specific group: 

$ TYPE *.DAT;* 

The TYPE command uses the file specification above to display only those 
files with file types of DAT out of all the files in the current default disk and 
directory. 

The following example shows how to select a group of files that begin with 
the same characters. Assume that all your subroutines for a tax program had 
file names beginning with the letters STAX, followed by 0 to 5 additional 
alphanumeric characters. You could select this group of files with the 
following file name specification: 

$ DIRECTORY STAX* 

To take another example, the more complex file specification *INS*9*.D*;1 
illustrates how to select such diverse files as the following: 

• AINST95.DAT; 1 

• INS9.D;1, 

• COBINS90A.DIR;1. 

The next example shows a wildcard used in a directory specification: 

$ DIRECTORY [ROGERS.*]*.DAT 

This example selects all files with a file type of DAT that exist in 
subdirectories one level below [ROGERS]. 

Consider another example where wildcard characters appear in the directory 
specification: 

$ TYPE [*.*.*]AVERAGE.*;* 
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This file specification selects all versions of all files named AVERAGE, with 
any file type, that exist in any second-level subdirectory on the current default 
disk. For example, this file specification will select [A.B.CJAVERAGE.DAT, 
but not [X.YjAVERAGE.DAT. 

It is also possible to use the asterisk wildcard character in directory 
specifications given in the UIC format (see Section 3.4.3). For example, 

[*,6] indicates all directories with any group number and a member number 
of 6. Since the search is limited to directories in UIC format, a directory 
specification of [*,*] does not include any of the named directories. However, 
[*] locates all named directories and all directories in the UIC format. 


3.7.1.2 The Match-Any-Character Wildcard Character (Percent Sign) 

The percent sign allows you to select files with any single character in the 
position that the percent sign occupies in the file specification. You can use 
the percent sign in the directory, file name, and file type fields. You cannot, 
however, use the percent sign in the version number field. For example: 

$ DIRECTORY [MALCOLM] CHAP*/,. DOC; * 

This file specification selects all versions of all files with a file type of DOC 
in the directory named [MALCOLM] that have file names beginning with 
CHAP followed by a single character. Files that might be selected include 
CHAPA.DOC, CHAP3.DOC, and so forth. Note, however, that CHAP.DOC 
is not selected, since it contains nothing in the percent sign position. 
Likewise, CHAPIX.DOC is ignored because it has too many characters after 
CHAP in its file name; the percent sign replaces only one character position 
in a field. 

You can specify the percent sign as many times as necessary, and in 
combination with other wildcard characters. Thus, if you want to select 
all versions of files with names starting with INS followed by any three 
characters before an A, and file types beginning with J, in directories whose 
names begin with MA, you would issue the following file specification: 

$ [MA*]INSmA*.J*;* 

Some of the files that would be selected by the above file specification 
include: 

[MAINE]INS 123 A.JNL; 1 
[MASSACHUS]INS854A89.JTK;43 
[MALCOLMJINS743A9. J; 13 
[MANDELL]INS912 A75 .JC;24 

The percent sign is not supported for the ANSI 17-character file names you 
can use with magnetic tape volumes. 


3.7.1.3 The Ellipsis Directory-Searching Wildcard Character 

The ellipsis indicates that you want to select files from a directory hierarchy, 
starting from a specified directory level and searching downward to lower 
levels of the directory hierarchy. For example: 

$ DIRECTORY [JONES...ANALYSIS]PQUEST.*;* 
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This file specification searches for all files named PQUEST in any of the 
subdirectories named [ANALYSIS] in any hierarchy under the directory 
[JONES]. Some of the files that would be selected include: 

[JONES.SALES. ANALYSIS]PQUEST.DAT;5 
[JONES.M ARKET.US A. AN ALYSIS]PQUEST.MEM; 12 
[JONES. ANALYSIS]PQUEST.TXT;25 

If you want to start a directory search from your default position (established 
by the system login, or defined by you with a SET DEFAULT command), you 
can begin the directory specification with a period or an ellipsis. 

For example, if your current default directory is [SMITH], the following 
command selects all subdirectories named [BCOMP] below the default 
directory [SMITH]. 

$ DIRECTORY [...BCOMP] 

This command would select files such as [SMITH.BCOMPJDIARY.TXT and 
[SMITH.WORK.BCOMPJEXP.DAT. However, if you issue the command: 

$ DIRECTORY [.BCOMP] 

files are selected from the [BCOMP] subdirectory that is 
one level lower than the current default directory. For 
example, the file [SMITH.BCOMPJDIARY.TXT is selected, but 
[SMITH.WORK.BCOMPJEXP.DAT is not. 

If you want to search all the way to the bottom of the directory hierarchy, 
you can use a directory specification that ends with an ellipsis. For example, 
if you want to search your default directory and all subdirectories below it, 
you can specify: 

$ DIRECTORY [...] 

The next example shows the use of multiple ellipses in one directory 
specification: 

$ DIRECTORY [...INVENTORY...]ZSTOCK.DAT 

This specification locates all files named ZSTOCK.DAT in all directories from 
the directory named [ . . . INVENTORY] below the default directory down 
to the bottom of the [ . . . INVENTORY] hierarchy. Note that in this case 
[ . . . INVENTORY] must occur on a path down from the current directory, 
and it must be at least one level below the current directory. 

The following example also illustrates the use of multiple ellipses in one 
directory specification: 

$ DIRECTORY [...INVENTORY...*]ZSTOCK.DAT 

In this case, however, the asterisk requires that ZSTOCK.DAT occur in 
at least one level of subdirectory below INVENTORY. In the previous 
example, a match would have occurred if ZSTOCK.DAT had been found 
in the [INVENTORY] directory itself. 

You can specify a search of all directories and subdirectories on the volume 
with the following specification: 

[*...] 

This specification searches down as many as eight levels of directory names 
(one top-level directory and seven subdirectories), if they exist. 
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3.7.1.4 The Hyphen Directory-Searching Wildcard Character 

The hyphen allows you to search up a directory hierarchy rather than down. 
A single hyphen will send the search back up one level from the default 
directory level. For example, to move from the subdirectory [JONES.TEST] to 
[JONES], you could issue the command: 

$ SET DEFAULT [-] 

If your default position in a directory hierarchy is 
[JONES.TEST.BACKUP.SRC], you could print the file 
[JONES.TEST.BACKUP.COM]HUMIDITY.LIS with the command: 

$ PRINT [-.COM]HUMIDITY.LIS 

In this example, the hyphen searches up one level to [JONES.TEST.BACKUP]. 
This name is concatenated to the subdirectory COM, to form the complete file 
specification [JONES.TEST.BACKUP.COM]HUMIDITY.LIS. 

You can specify more than one hyphen, as shown below: 

$ DIRECTORY [--.COMPUTE] 

In this example, you search up the hierarchy two levels, to the directory 
[JONES.TEST]. Then you move down to [JONES.TEST.COMPUTE]. 

You will get an error message if you issue so many hyphens that you point 
above the device's top directory level; remember that the VAX/VMS operating 
system permits up to eight levels of directory names (one top-level directory 
and seven subdirectories.) 


3.7.2 Using Wildcards in Output File Specifications 

The following sections describe how to use wildcards in output file 
specifications. Only one of the wildcard characters, the asterisk, is allowed 
in the name, type, and version fields for output file specifications. In output 
directory specifications, two wildcard characters are allowed: the asterisk and 
the ellipsis. 


3.7.2.1 Using Wildcards in Output File Names 

You can use the asterisk in the name, type, and version fields in output file 
specifications. When used in an output specification, the asterisk indicates a 
temporary default. That is, you want the selection of the output files to follow 
the corresponding field in the input specification. Some commands apply 
their own defaults to the output file type when it is absent. Section 2.4.4 
describes the rules for resolving defaults in output file specifications. 

The following example illustrates how DCL interprets asterisks in the output 
file specifications of the COPY command: 

$ COPY [MALCOLM]*.*;* USE1:[SAVE.JULY]*.*;* 

The COPY command generally copies the contents of a specified input 
file into a new output file. Using wildcard characters, you can copy large 
numbers of files without naming them individually. In this case, all the 
files in the directory named [MALCOLM] are copied to a directory named 
[SAVE.JULY] on a device with the logical name USE1. The file specifications 
of the copies are the same as those of the original files. 
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3.7.2.2 


The following list provides additional examples of asterisk use in output file 
specifications. 


Example 

Explanation 

$ COPY TEST.DAT *.OLD 

Copies the highest version of the file 
TEST.DAT from the current default disk 
and directory into a file named TEST.OLD. 

$ COPY [BARNEY]*.FOR * 

Copies the highest version of each file 
with a file type of FOR in the directory 
[BARNEY] on the current default disk to 
new files in the current default directory. 
The new files will have the same file 
names as the original files, and the file 
type FOR. 


Note that you cannot use the asterisk wildcard to specify partial name 
changes. For example, the following command is invalid: 

$ RENAME *1.DAT *2.DAT 


Using Wildcards in Output Directory Specifications 

Wildcard characters are used in output directory specifications to refer to 
output directory levels by general names rather than by specific names. 

By including wildcards in output directory specifications, you can use the 
BACKUP command to duplicate an entire input directory specification, or 
move files from one directory tree into another directory tree at the same or 
at a different level. 

Each wildcard character in an output directory specification refers to 
a corresponding directory level in the input specification. An output 
specification may contain only wildcards, or it may contain a combination 
of wildcards and directory names. However, if directory names are used, they 
must always precede the specification of wildcards. 

Unlike input specifications, output directory specifications allow only two 
wildcard characters: 

• Asterisk (*) 

• Ellipsis (...) 

The asterisk indicates that you want a particular level in the output 
directory specification to match a level indicated by a wildcard in the input 
specification. 

For example: 

$ BACKUP [JONES.*]*.*;* [SMITH.USER.*]*.*;* 

This BACKUP command copies all the files from the subdirectories of [JONES] 
to the corresponding subdirectories of [SMITH.USER]. If the directory [JONES] 
has a subdirectory [JONES.SUB], then all the files in that subdirectory are 
copied to the subdirectory [SMITH.USER.SUB]. Notice that the single asterisk 
in the output directory specification refers to the first subdirectory level (in 
the input directory) that was wildcarded (in this case, the subdirectory SUB). 

The ellipsis indicates that you want the output directory specification to 
follow the same hierarchical structure as the input directory subtree, from the 
first level that was wildcarded downward. For example: 

$ BACKUP [JONES.SUB...]*.*.* [SMITH...]*.*.* 
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This command copies all the files in [JONES.SUB] to a directory named 
[SMITH], and all the files in all the subdirectories in [JONES.SUB] to the 
corresponding subdirectories of [SMITH]. The trailing ellipsis in the output 
specification allows you to move the entire third-level directory subtree from 
the input directory to a second-level subtree in the output directory. 

For output directory specifications, a trailing asterisk and ellipsis are mutually 
exclusive whenever they follow a specific directory name. Therefore, output 
directory specifications such as [USER.* . . . ] and [USER . . . *] are invalid. 
However, [*...] is valid, because the asterisk wildcard is used in place of a 
directory name. 

By using the BACKUP command and specifying an output directory 
specification entirely by wildcards, you can move an entire input directory 
structure to an output directory structure. You can specify an output directory 
entirely by wildcards in either of the following ways: 

$ BACKUP DB1:[JONES...]*.*;* DB2: [*]*.*;* 

or 

$ BACKUP DB1:[JONES...]*.*;* DB2:[*...]*.*;* 

These commands allow you to move all the files in the [JONES] subtree on 
DB1 to the [JONES] subtree on DB2, copying all the files from the top-level 
[JONES] directory downward through the entire directory tree, including any 
subtrees that may exist. 

You can also use wildcards in UlC-formatted output directories whenever the 
input directory specification is in UIC format. In UlC-formatted output 
directory specifications, the output directory field that is wildcarded is 
replaced by the corresponding input field. For example: 

$ BACKUP DB1:[010,*]*.*;* DB2: [*,017]*.*;* 

In this command, the group field from the input directory (010) is substituted 
for the group field that is wildcarded in the output directory. In this example, 
if there is only one directory on DB1, [010,100], whose group number matches 
the input directory specification on DB1, all the files in [010,100] on DB1 are 
copied to the output directory [010,017] on DB2. If there is more than one 
input directory having the group field 010, all the files in all the directories 
having that group field are copied to the output directory [010,017]. 

In summary, the following rules apply to output directory wildcarding: 

• An output directory specification composed entirely of wildcards is 
replaced by the entire input directory structure. 

• Trailing asterisks in an output directory are replaced by (sub)directories 
from the related input file directory, beginning with the first wildcarded 
directory in the related input file. 

• A trailing ellipsis in the output directory is replaced by the subtree from 
the related input directory, beginning with the first wildcarded directory in 
the related input file. If, at the current moment, there are no wildcarded 
directories in the input file specification, then the trailing ellipsis in the 
output file specification is temporarily ignored for purposes of directory 
name substitution. 
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An asterisk and ellipsis may not both trail in an output directory 
specification if a directory name is also specified. 

UlC-formatted output directory specifications may only receive related file 
defaults from UlC-formatted directories. 

Non-UIC-formatted output directory specifications may only receive 
related file defaults from non-UIC-formatted directories. 
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A logical name is a name that is equated to an equivalence string, or to a list 
of equivalence strings. An equivalence string can be any group of characters. 
However, most often an equivalence string is a file specification, a device 
name, or another logical name. When you issue DCL commands, you can use 
logical names instead of file specifications or device names, and the system 
will translate the logical name to supply the corresponding equivalence string. 
Logical names can be defined by users or by the system. 

You can use logical names as a shorthand way of specifying files or directories 
that you refer to frequently. For example, you might assign the logical name 
HOME to your default disk and directory, or the logical name DIARY to a 
file in which you keep a log of your day's activities. You can also use logical 
names in file specifications to keep your programs and command procedures 
independent of physical file specifications. 

Another common use for logical names is to refer to physical devices. 

For example, you can assign logical names to devices such as tape drives, 
terminals, and line printers. Also, the system manager assigns logical names 
to public disk volumes, so that users do not have to be concerned with the 
physical location of those volumes. 


4.1 Creating and Deleting Logical Names 

DCL provides two commands for creating logical names: ASSIGN and 
DEFINE. Both commands equate a logical name to an equivalence string, 
or to a list of strings. Logical names and their equivalence strings can each 
have a maximum of 255 characters, and can be used to form all or part of a 
file specification. This chapter uses the DEFINE command to create logical 
names; see the VAX/VMS DCL Dictionary for information on using ASSIGN. 
(Note that the syntax for the ASSIGN command differs from the syntax for 
the DEFINE command.) 

The following command creates the logical name DIARY and equates this 
name to the equivalence string USEl:[MALCOLM.PERSONAL]DIARY.TXT: 

$ DEFINE DIARY USE1:[MALCOLM.PERSONAL]DIARY.TXT 

To refer to the file, you can use the logical name DIARY in place of the actual 
file specification. For example: 

$ EDIT DIARY 

When you issue this command, the system translates the logical name DIARY 
to its equivalence string USEl:[MALCOLM.PERSONAL]DIARY.TXT. 

When you use a logical name as part of a file specification, the logical 
name must be the leftmost component of the file specification and must be 
terminated by a colon (:). For example, the logical name TAXES can be 
assigned to directory name [OBRIEN.TAXES] as follows: 

$ DEFINE TAXES [OBRIEN.TAXES] 
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You can now use the logical name TAXES as part of a file specification to 
access files in the directory [OBRIEN.TAXES]. For example: 

$ PRINT TAXES:JANUARY.DAT 

When you specify equivalence strings with the DEFINE command, you must 
include the punctuation marks (colons, brackets, periods) that would be 
required if the equivalence strings were part of a file specification. Therefore, 
if you specify a device name as an equivalence string, you must terminate the 
device name with a colon (:). However, if you specify a device and directory 
name, or a full file specification, do not terminate the equivalence string with 
a colon. 

The following examples show how to use colons in logical name assignments. 
In the first example, the following equivalence string contains a device and 
a directory name. You need to include the colon to separate the device and 
directory names, but you do not terminate the equivalence string with a 
colon. 

$ DEFINE SCRATCH DMA1:[MAGGIE] 

This DEFINE command assigns the logical name SCRATCH to the directory 
named [MAGGIE] on the device DMA1. 

The next example shows an equivalence string that consists only of a device 
name. The equivalence string must be terminated with a colon, as shown 
below: 

$ DEFINE SAVE DMA1: 

The DEFINE command assigns the logical name SAVE to the disk DMA1:. 
After issuing this DEFINE command, you can use the logical name SAVE in 
place of the device name field when referring to the device. For example, 
the following COPY command transfers files from the current default disk 
and directory to the [MALCOLM] directory on the device DMA1 by using the 
logical name SAVE. 

$ COPY *.* SAVE:[MALCOLM]*.* 

Although the equivalence string DMA1: contains a colon, you must also use 
a colon to terminate the logical name SAVE when it is the leftmost portion of 
a file specification. 

Note: You can optionally terminate a logical name with a colon. If you do this, 
the ASSIGN command removes the colon before placing the logical name 
in a logical name table. The DEFINE command, on the other hand, does 
not remove the colon before placing the name in a logical name table. 

In general, you should not specify a colon at the end of a logical name 
when you are creating the logical name assignment. However, if you do 
specify a colon at the end of a logical name, and if you want to save the 
colon as part of the logical name, you must use the DEFINE command to 
create the logical name. 

When you deassign a logical name ending with a colon, you need to 
specify two colons. 
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To delete a logical name, use the DEASSIGN command. For example: 

$ DEFINE TEST [JONES] 


$ DEASSIGN TEST 


4.2 Displaying Logical Names 

To display the value of a logical name, use the SHOW LOGICAL or the 
SHOW TRANSLATION command. For example: 

$ SHOW LOGICAL TEMP 

"TEMP" = "DMA1:[MAGGIE]" (LNM$PROCESS_TABLE) 

This example shows that the logical name TEMP has the equivalence string 
DMA1:[MAGGIE]. The output also shows that the name TEMP exists in the 
process logical name table (LNM$PROCESS_TABLE). (See Section 4.3 for 
more information on logical name tables.) 

If more than one translation was performed to get the final equivalence string, 
the display from the SHOW LOGICAL command has multiple lines, with the 
second and following lines showing the level number of the translation. For 
example: 

$ SHOW LOGICAL MYDISK 

"MYDISK" * "W0RK4" (LNM$PROCESS_TABLE) 

1 "W0RK4" * "$255$DUA17:" (LNM|SYSTEM_TABLE) 

Level numbers are zero based; that is, 0 is the first level, 1 is the second, and 
so on. In this example, two translations were performed, and the number 1 
indicates the second level of translation. 

If you have a logical name in more than one table, you can issue the 
following command to display the name in each table: 

$ SHOW LOGICAL/TABLE=* TESTNAME 

"TESTNAME" = "[ODONNELL]" (LNM$PROCESS_TABLE) 

"TESTNAME" = "[ODONNELL]" (NEWTAB) 

In this example, the logical name TESTNAME exists in both 
LNM$PROCESS_TABLE and in a user-defined table named NEWTAB. 

Unless the search order has been redefined for your process, you can display 
the contents of the process, job, group, and system logical name tables by 
entering the SHOW LOGICAL command without qualifiers or parameters: 

$ SHOW LOGICAL 

This command produces a display of the current logical names in all four 
tables, and their equivalence strings. 

You can request the system to display all the entries in only a specified logical 
name table by using the /TABLE qualifier. For example: 

$ SHOW LOGICAL/TABLE=LNM$GROUP 

This SHOW LOGICAL command produces a display of all current entries in 
the group logical name table. 
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4.3 Logical Name Tables 

The system maintains logical names in logical name tables. Some logical 
name tables are process private; that is, they are available only to your 
process. Other tables are shared with other users on the system. By default, 
you use names from the following four tables: 

• Your process table 

• The job table for your process 

• Your group table 

• The system table 

These tables are described in the following sections. 


4.3.1 The Process Table 

Your process table contains logical names that are available only to your 
process. The actual name for your process table is LNM$PROCESS_TABLE. 
However, you should use the logical name LNM$PROCESS to refer to your 
process table. For example, the following command displays the names in 
your process table: 

$ SHOW LOGICAL/TABLE=LNM$PROCESS 

By default, the DEFINE and DEASSIGN commands place names in and delete 
names from your process table. 

When you log in, the VAX/VMS operating system creates logical names for 
your process, and places these names in your process table. These default 
process logical names are listed in Table 4-1. 


Table 4-1 Default Process Logical Names 


Logical Name 

Description 

SYS$COMMAND 

Original (first-level) SYSSINPUT stream. 

SYSSDISK 

Default device established at login or changed by the SET 
DEFAULT command. 

SYSSERROR 

Default device or file where the system writes messages. 

SYSSINPUT 

Default input stream for the process. 

SYSSNET 

The source process that invokes a target process in 
DECnet-VAX task-to-task communication. When opened 
by the target process, SYSSNET represents the logical 
link over which that process can exchange data with its 
partner. SYSSNET is defined only during task-to-task 
communication. 

SYSSOUTPUT 

Default output stream for the process. 

TT 

Default device name for terminals. 


Note that SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND 
define files that remain open for the life of the process. See Section 4.10 for 
more information on process permanent files. 
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4.3.2 The Job Table 


The job table contains logical names that are available to your process 
and to any of your subprocesses (that is, to your process and all of its 
descendant subprocesses in the job tree). The actual name for your job table 
is LNM$JOB_xxx (where xxx is a unique number for your job tree). However, 
you should use the logical name LNM$JOB to refer to your job table. 

When you log in, the VAX/VMS operating system creates certain logical 
names and places them in the job logical name table. These names are listed 
in Table 4-2. 


Table 4-2 Default Job Logical Names 


Logical Name 

Description 

SYS$LOGIN 

Device and directory established at login time as the 
home directory for the process. 

SYS$LOGIN_DEVICE 

The device portion of SYSSLOGIN. 

SYS$REM_ID 

For jobs initiated through a DECnet network connection, 
the identification of the process on the remote node 
from which the job was originated. On VAX/VMS 
systems, this identification is the process' username if 
proxy logins are enabled, or the process identification 
number (PID) if proxy logins are not enabled. See 
the Guide to VAX/VMS System Security for more 
information about proxy logins. Other operating systems 
may send other data (terminal numbers, for example) as 
the remote process identification. 

SYS$REM_NODE 

For jobs initiated through a DECnet network connection, 
the name of the remote node from which the job was 
originated. 

SYSSSCRATCH 

Default device and directory to which temporary files are 
written. 


4.3.3 The Group Table 

The group table contains logical names that are available to all users 
in your UIC group number. The actual name for your group table is 
LNM$GROUP—xxx (where xxx represents your group number). However, 
use the logical name LNM$GROUP to refer to your group table. To create 
or delete a name in your group table, you need the user privilege GRPNAM, 
GRPPRV, or SYSPRV. 
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4.3.4 The System Table 

The system table contains logical names that are available to all users on the 
system. The actual name for your system table is LNM$SYSTEM__TABLE. 
However, you should use the logical name LNM$SYSTEM to refer to the 
system table. To create or delete a name in the system table, you need the 
user privilege SYSNAM or SYSPRV. 

In addition to the names that the system manager at your installation places 
in the system table, the system table contains the names shown in the 
following table. 


Table 4-3 Default System Logical Names 


Logical Name 
DBG$INPUT 

DBG$OUTPUT 

SYSSCOMMON 

SYSSERRORLOG 

SYSSEXAMPLES 

SYS$HELP 

SYS$INSTRUCTION 

SYSSLIBRARY 

SYSSMAINTENANCE 

SYSSMANAGER 

SYS$MESSAGE 

SYS$NODE 

SYS$SHARE 

SYS$SPECIFIC 

SYS$SYSDEVICE 

SYSSSYSROOT 


SYS$SYSTEM 

SYSSTEST 

SYSSUPDATE 


Description 

Default input stream for the VAX/VMS Debugger; 
equated to SYSSINPUT. 

Default output stream for the VAX/VMS Debugger; 
equated to SYS$OUTPUT. 

Device and directory name for the common part of 
SYSSSYSROOT. (Note that for non-common system 
disks, this will be identical to SYSSSPECIFIC.) 

Device and directory name of error log data files. 

Device and directory name of system examples. 

Device and directory name of system help files. 

Device and directory name of system instruction data 
files. 

Device and directory name of system libraries. 

Device and directory name of system maintenance files. 
Device and directory name of system manager files. 
Device and directory name of system message files. 

Network node name for the local system if DECnet-VAX 
is active on the system. 

Device and directory name of system shareable images. 

Device and directory name for node-specific part of 
SYSSSYSROOT. 

VAX/VMS system disk containing system directories. 

Device and root directory for system directories. (For a 
common system disk, this logical name will be defined 
as a search list which consists of the node-specific 
device and directory, and the common device and 
directory. For a non-common system disk, this logical 
name will only consist of the node-specific device and 
directory.) 

Device and directory of operating system programs and 
procedures. 

Device and directory name of User Environment Test 
Package (UETP) files. 

Device and directory name of system update files. 
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4.4 Logical Name Directory Tables 

The system provides two directory tables to catalog your logical name 
tables. These directories also contain logical names that translate iteratively 
to table names. Your process private tables are cataloged in the table 
LNM$PROCESS_DIRECTORY; your shareable tables are cataloged in the 
table LNM$SYSTEM_DIRECTORY. 

All names contained in a directory table must be no more than 31 characters 
long, and must not contain characters other than alphanumeric characters, the 
dollar sign ($), and the underscore (_). 


4.4.1 The Process Directory Table 

By default, the process directory logical name table LNMSPROCESS— 
DIRECTORY contains the following logical names when you log in. 


Table 4-4 Default Process Directory Logical Names 


Logical Name 

Description 

LNMSGROUP 

A logical name that equates to the 
equivalence string LNM$GROUP_xxx, 
where xxx represents your group number. 
LNM$GROUP_xxx is the logical name table 
that is used by your UIC group. (The table 
LNM$GROUP_xxx is cataloged in the system 
directory table.) Therefore, LNMSGROUP is 
a logical name that translates iteratively to 
the name of your group logical name table. 

LNM$JOB 

A logical name that equates to the 
equivalence string LNM$JOB_xxx, where 
xxx represents a number unique to your 
job tree. LNM$JOB_xxx is the logical name 
table that is used by your job. (The table 
LNM$JOB_xxx is cataloged in the system 
directory table.) Therefore, LNMSJOB is a 
logical name that translates iteratively to the 
name of your job logical name table. 

LNMSPROCESS 

A logical name that equates to the 
equivalence string LNM$PROCESS_TABLE. 
Therefore, LNMSPROCESS is a logical name 
that translates iteratively to the name of 
your process logical name table. 

LNM$PROCESS_DIRECTORY 

The name of your process directory logical 
name table. 

LNM$PROCESS_T ABLE 

The name of your process logical name 
table. 


To see the logical names in LNM$PROCESS_DIRECTORY, issue the 
command: 

$ SHOW LOGICAL/TABLE*LNM$PROCESS_DIRECTORY 
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4.4.2 The System Directory Table 

By default, the system directory logical name table LNM$SYSTEM_ 
DIRECTORY contains the following logical names. 


Table 4-5 Default System Directory Logical Names 


Logical Name 

LNM$DCL—LOGICAL 


LNM$DIRECTORIES 


LNM$FILE_DEV 


LNM$GROUP_xxx 


LNM$JOB_xxx 


LNM$PERMANENT_MAILBOX 


Description 

A logical name that equates to the 
equivalence string LNM$FILE_DEV. This 
logical name iteratively translates into the 
list of logical name tables searched and 
displayed by the SHOW LOGICAL and 
SHOW TRANSLATION commands and the 
FSTRNLNM lexical function. By default, 
these commands search and display the 
process, job, group, and system logical 
name tables, in that order. 

A logical name that equates to the following 
equivalence strings: LNM$PROCESS_ 
DIRECTORY and LNMSSYSTEM— 
DIRECTORY. 

A logical name that equates to 
the following equivalence strings: 
LNMSPROCESS, LNMSJOB, LNM$GROUP, 
and LNMSSYSTEM. These logical names 
translate iteratively to the process, job, 
group, and system logical name tables. 

This logical name iteratively translates to 
the list of logical name tables searched 
by the system whenever it attempts to 
iteratively translate a logical name used in a 
file specification or device name. By default, 
the process, job, group, and system logical 
name tables are searched, in that order. 

The name of a group logical name table. 
The characters xxx represent a particular 
group number. There is an LNM$GROUP_ 
xxx logical name table for each group in the 
system. 

The name of a job logical name table. The 
characters xxx represent a number unique 
to this job tree. There is an LNM$JOB_ 
xxx logical name table for each job in the 
system. 

A logical name that equates to the 
equivalence string LNMSSYSTEM. (Logical 
names associated with permanent 
mailboxes are entered in the logical 
name table to which the logical name 
LNM$PERMANENT_MAILBOX iteratively 
translates.) 
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Table 4-5 (Cont.) Default System Directory Logical Names 


Logical Name 

Description 

LNMSSYSTEM 

A logical name that equates to the 
equivalence string LNM$SYSTEM_TABLE. 
Therefore, LNMSSYSTEM is a logical name 
that translates iteratively to the name of the 
system logical name table. 

LNN$SYSTEM_DIRECTORY 

The name of the system directory logical 
name table. 

LNM$SY STEM _T ABLE 

The name of the system logical name table. 

LNM$TEMPORARY_MAILBOX 

A logical name that equates to the 
equivalence string LNMSJOB. (Logical 
names associated with temporary mailboxes 
are entered in the logical name table to 
which the logical name LNM$TEMPORARY_ 
MAILBOX iteratively translates.) 


4.5 Logical Name Access Modes and Attributes 

When you create a logical name, the name has an associated access mode. In 
addition, you can specify optional attributes for the name. 

A logical name that you create with DCL commands can have an access 
mode of user, supervisor, or executive. Unless you explicitly specify the 
/USER_MODE or /EXECUTIVE—MODE qualifier, logical names are created 
in supervisor mode. For example: 

$ DEFINE TEST USE1: 

$ DEFINE/EXECUTIVE.MODE TEST USE1: 

The first command places the logical name TEST in the process logical name 
table in supervisor mode. The second command places the logical name 
TEST in the process logical name table in executive mode. (You must have 
SYSNAM privilege to create an executive mode logical name; if you do not 
have SYSNAM privilege, the name will be created in supervisor mode, even 
though you specified executive mode.) After you issue these commands, two 
logical names called TEST exist in the process table. 

Access modes are organized from outer to inner, with an inner mode being 
more privileged than an outer mode. User mode is the outermost mode; 
executive mode is the innermost mode. User-mode logical names are 
temporary; they are deleted when the current image (or the next image, if 
none is currently active) terminates. 

During VAX/VMS system operations where the integrity of the system could 
be compromised by incorrect logical names (such as in the activation of 
privileged images) only executive-mode and kernel-mode logical names are 
used; supervisor-mode and user-mode names are ignored. DIGITAL therefore 
recommends that logical names for important system components (public 
disks and directories, for example) be defined in executive mode , using the 
DCL command DEFINE/SYSTEM/EXECUTIVE. (Only the operating system 
and privileged programs can create logical names in kernel-mode.) 
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You can specify special attributes for logical names when you create them. 
For example: 

$ DEFINE/NAME_ATTRIBUTES=CONFINE HOME USE1:[JONES] 

The logical name HOME is created in the process logical name table, in 
supervisor mode, with the CONFINE attribute. CONFINE indicates that 
the logical name HOME will not be copied to a subprocess created by the 
SPAWN command. When you issue the SHOW LOGICAL command and 
specify the /FULL qualifier, the access mode and any name attributes are also 
displayed. For example: 

$ SHOW LOGICAL/FULL HOME 

"TEST" [super,confine] = "USE1:[JONES]" (LNM$PROCESS_TABLE) 

You can also specify translation attributes that modify how the translation 
is to be interpreted. See Section 4.6.2 for more information on translation 
attributes. 


4.6 Logical Name Translation 

When the system reads a file specification or device name in a DCL command 
string, it examines the parameter to see if the leftmost component is a logical 
name. If the leftmost component is delimited by a colon, space, comma, or an 
end-of-line, then the system attempts to translate the component as a logical 
name. If the leftmost component ends with any other character, then the 
system does not attempt to translate the component as a logical name. 

For example, the system will identify the leftmost components of the 
following file specifications, and will perform logical name translation if 
appropriate. 

$ TYPE ALPHA 
$ TYPE DISK:ALPHA 
$ TYPE [MALCOLM]ALPHA 

When the system reads the file specification ALPHA in the first example, it 
checks to see if ALPHA is a logical name because ALPHA is the leftmost (and 
in this example, the only) component of the file specification. In the second 
example, the system checks to see if DISK is a logical name because it is the 
leftmost component and it ends with a colon; it does not check ALPHA. In 
the third example, the system does not perform logical name translation on 
the file specification [MALCOLMJALPHA because the leftmost component 
ends with a bracket. 

By default, when the system translates logical names, it searches the process, 
job, group, and system tables, in that order, and uses the first match it 
finds. However, if the logical name LNM$FILE_DEV is redefined within the 
system directory table, or if a process-private definition of LNM$FILE_DEV 
is created within the process directory table, then the system searches the 
specified tables. For example: 

$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY - 
_$ LNM$FILE_DEV LNM$PROCESS, LNM$SYSTEM 

In this example, a process-private version of LNM$FILE_DEV is defined so 
that LNM$JOB and LNM$GROUP are omitted. When a logical name is used 
in a file specification, the job and group tables will not be searched during 
logical name translation. 
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4.6.1 Iterative Translation 

When the system translates logical names used as file specifications or 
devices, the logical name translation can be iterative. This means that after 
the system translates a logical name, it repeats the process of translating the 
file specification. For example, consider logical name table entries made with 
DEFINE commands as follows: 

$ DEFINE DISK DBA1: 

$ DEFINE REPORT DISK:[MALCOLM.SUMMARY]WEATHER.SUM 

The first DEFINE command equates the logical name DISK to the device name 
DBA1. The second DEFINE command equates the logical name REPORT to 
the file specification DISK:[MALCOLM.SUMMARY]WEATHER.SUM. In 
subsequent commands or in programs you execute, you can refer to the 
logical name REPORT. For example: 

$ TYPE REPORT 

When the system translates the logical name REPORT, it finds the equivalence 
string DISK:[MALCOLM.SUMMARY]WEATHER.SUM. It then checks to see 
if the leftmost component in this file specification ends in a colon, a space, 
a comma, or an end-of-line. If it does (as DISK does in this example), the 
system translates that logical name also. When the logical name translation is 
complete, the translated file specification is as follows: 

DBAl:[MALCOLM.SUMMARY]WEATHER.SUM 

The system limits the number of levels to which it performs logical name 
translation. The number of levels varies among system facilities, but it is at 
least nine. If you define more than the system-determined number of levels, 
or if you create a circular definition, an error occurs when the logical name is 
used. 


4.6.2 Translation Attributes 

When you create a logical name, you can specify optional translation 
attributes that are applied to some or all of its equivalence strings. These 
attributes modify the interpretation of the equivalence string. For example, 
the CONCEALED attribute indicates that an equivalence string is to be 
concealed; the string is not displayed in system messages that refer to the 
logical name. The TERMINAL attribute indicates that an equivalence string is 
not a candidate for iterative translation. 

The qualifier used for applying translation attributes, /TRANSLATION— 
ATTRIBUTES, is a positional qualifier. Thus, you can use this qualifier to 
apply translation attributes to all equivalence strings of a logical name or only 
to certain equivalence strings. 
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4.6.2.1 Concealed Device Names 

A concealed device name is a special type of logical name for devices. A 
concealed device name causes the logical name for the device to be shown 
in system displays (on your terminal) rather than the physical name for the 
device. The equivalence string of a concealed device name must be a physical 
device name. 

Use the CONCEALED attribute to create a concealed device name, as shown 
in the following example. 

$ DEFINE/TRANSLATION jmTUBUTES=CONCEALED DISK DMA3: 

$ SHOW LOGICAL/FULL DISK 

"DISK" [super] = "DMA3" [concealed] (LNM$PROCESS_TABLE) 

$ COPY/LOG A.DAT [.SUB]*.* 

y,C0PY-S-C0PIED, DISK: [MALCOLM]A.DAT; 1 copied to DISK: [MALCOLM. 

SUB]A.DAT;1 

Although SHOW LOGICAL/FULL DISK demonstrates that the assignment 
has taken place, the log message from the COPY/LOG command shows 
the logical name DISK rather than the equivalence string DMA3 as the 
default disk. The physical device is "transparent'" unless you explicitly request 
translation of its logical name; in other words, the device is a concealed 
device. 

Using concealed devices allows you to write programs and command 
procedures or to perform other operations without being concerned about 
which physical device a volume is mounted on, and also allows you to use 
names that are more meaningful than the physical device names. 


4.6.2.2 Non-Iterative Translation 

Use the TERMINAL translation attribute to indicate that an equivalence string 
of a logical name should not be translated iteratively. That is, the equivalence 
string is not examined to see if it is also a logical name. The translation is 
"terminal" (final, or completed) after the first translation. 

The following example defines a logical name whose equivalence string is 
assigned the terminal attribute: 

$ DEFINE/TRANSLATION JITTRIBUTES-TERMINAL USED1 DBA2: 

When the logical name USED1 is used, it refers to the physical device DBA2:, 
even if a logical name DBA2 exists with some other translation. (However, 
to avoid possible confusion and errors, we recommend that you do not use 
physical device names as logical names.) 


4.6.3 Applying Defaults During Logical Name Translation 

When the system completes the translation of a logical name, it uses defaults 
to fill in any still-unspecified fields in the file specification. In the above 
examples, the system completes the file specifications by supplying the 
current default device, directory and version number. 

Many commands create output files automatically and provide default file 
types for the output files. When you use a logical name to specify the input 
file for a command, the command uses the logical name to assign a file 
specification to the output file as well. Thus if the equivalence string contains 
a file name and file type, the output file is given the same file name and file 
type as the input file but a higher version number. 
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For example, the LINK command creates, by default, an executable image file 
that has the same file name as the input file and a default file type of EXE. If 
you make a logical name assignment as shown below, and if you invoke the 
LINK command, the results may not be what you expect. 

$ DEFINE TESTIT RANDOM.OBJ 
$ LINK TESTIT 

In this example, the translation of the logical name TESTIT provides the file 
RANDOM.OBJ as input to the linker. When the linker creates the output 
file, it uses the same logical name (TESTIT) to create the output file. Because 
the equivalence string (RANDOM.OBJ) has a file type, the default output 
file type of EXE is overridden. Therefore, the executable image is named 
RANDOM.OBJ, and it has a version number one higher than the version 
number of the input file. To avoid this situation, omit the file type (OBJ) from 
the file specification when you define the logical name TESTIT. The linker 
will then use the default types for the input file (OBJ) and the output file 
(EXE). 


4.6.4 Translation of Logical Names in Input File Lists 

When you issue a command that accepts multiple input files and when you 
use logical names in the specifications of one or more files in the list, the 
equivalence string of each logical name provides a temporary default. For 
example: 

$ SET DEFAULT DBA2: [CASEY] 

$ DEFINE MAL DBA1:[MALCOLM] 

$ DEFINE HIG [HIGGINS] 

$ PRINT ALPHA,- 
_$ MAL:BETA,- 
_$ HIG:GAMMA 

The PRINT command looks for the following files: 

DB A2: [C ASEY] ALPHA. LIS 
DBAl:[MALCOLM]BETA.LIS 
DBA1 :[HIGGINS]GAMMA.LIS 

The device name in the equivalence string for the logical name MAL 
defines DBA1 as the temporary default device for this PRINT command. 
See Section 2.3.2 for more information on temporary defaults. 


4.7 Creating Logical Name Tables 

Use the CREATE/NAME—TABLE command to create new logical tables. The 
CREATE/NAME—TABLE command creates a logical name table and enters 
its name in one of the directory logical name tables. Logical name table 
names, or logical names that translate iteratively to logical name tables, must 
always be entered into one of the directory logical name tables. The logical 
name table name must be no more than 31 characters, and must not contain 
characters other than alphanumerics, the underscore, and the dollar sign. 

You can create logical name tables that are process-private or shareable. If 
the table is created as process private (the default), its name is entered in 
LNM$PROCESS_DIRECTORY. If the table is created as shareable, its name 
is entered in LNM$SYSTEM-DIRECTORY. 
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The following example shows how to create a new process private (the 
default) table, and verify that the table was created. 

$ CREATE/NAME.TABLE NEWTAB 
$ SHOW LOGICAL/TABLE=LNM$PROCESS_DIRECTORY 


4.7.1 Creating and Using Shareable Logical Name Tables 

To create a shareable logical name table, you must use the /PARENT qualifier 

specifying LNM$SYSTEM_DIRECTORY. 

The following privilege and access requirements apply to the use of shareable 

logical name tables: 

• To create a shareable logical name table, you must have the user privilege 
SYSPRV, and you must have "enable" (E) access to the parent table. 

• To delete a shareable logical name table, you must have the user privilege 
SYSPRV, or you must have "delete" (D) access to the table. 

• To place a name in or delete a name from a shareable logical name table, 
you must have "write" (W) access to the table. 

• To read (translate) a name in a shareable logical name table, you must 
have "read" (R) access to the table. 


4.7.2 Quotas for Logical Name Tables 

Quotas are used to limit the amount of system resources that a given logical 
name table can consume. When you create a logical name table, you can 
specify a quota to limit the number of bytes of paged pool that the table can 
use. (If you do not specify a quota, the table has an unlimited quota.) Before 
a logical name is created, the size of the data structure associated with the 
logical name entry is checked against the quota remaining for the table in 
which the name is to be entered. 

If there is insufficient quota available in the parent logical name table for the 
creation of a new table entry, the system will issue the SS$_EXLNMQUOTA 
error message. Since you cannot modify the quota of the parent logical name 
table, you must delete old table entries to provide space for your new table 
entries. 

For example, to create a logical name table named ABC and give it a quota of 
500 bytes you would enter the following command: 

$ CREATE/NAME_TABLE/PARENT_TABLE=LNM$SYSTEM_DIRECT0RY/QU0TA=5OO ABC 

The process, group, and system logical name tables have an infinite quota. 
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4.7.3 Job Logical Name Table Quota 

The job logical name table is a shareable table. There is one job logical name 
table for each job tree in the system, and the logical names in the job logical 
name table are available to all processes in that job tree. Several logical 
names are placed in the job logical name table by default (see Section 4.3.2); 
in addition, logical names created when volumes are mounted and when 
temporary mailboxes are created and placed in the job logical name table. 

The quota for a job logical name table is established when the table is created. 
The quota is determined by whichever of the following applies: 

• The JTQUOTA value established for the user in the system user 
authorization file, SYSUAF.DAT (if the first image activated by the process 
was the VAX/VMS system image LOGINOUT). 

• The PQL$_JTQUOTA quota list value specified in the call to the Create 
Process ($CREPRC) system service. 

• The /JOB_TABLE_QUOTA qualifier value on the RUN command used to 
create the detached process. 

• The SYSGEN parameter PQL_DJTQUOTA (if none of the preceding 
conditions applies). The standard default value for this parameter 

is 1024 bytes; however, your system manager can change it. The 
SYSGEN utility can be used to display and set the values of the 
parameters PQL_DJTQUOTA (default job logical name table quota) 
and PQL_MJTQUOTA (minimum job logical name table quota). 

A quota value of 0 for a job logical name table specifies that the quota is, for 
all practical purposes, unlimited. 


4.7.4 Logical Name Table Access Modes and Attributes 

When you create a logical name table, the table has an associated access 
mode. In addition, you can specify optional attributes for the table. 

As with other logical names, a logical name table can have an access mode 
of user, supervisor, or executive. Unless you explictly specify the /USER— 
MODE or /EXECUTIVE—MODE qualifier, logical name tables are created in 
supervisor mode. Access modes are organized from outer to inner, with an 
inner mode being more privileged than an outer mode. User mode is the 
outermost mode; executive mode is the innermost mode. For example: 

$ CREATE/NAME_TABLE TABLE1 
$ CREATE/NAME_TABLE/EXECUTIVE_MODE TABLE1 

The first command places the supervisor-mode logical name table called 
TABLE 1 into the process directory table. The second command places another 
logical name table called TABLE 1 in the process directory table. The second 
table is created in executive mode. (You must have SYSNAM privilege to 
create a logical name table in executive mode; if you do not have SYSNAM 
privilege, the logical name table is created in supervisor mode even though 
you specified /EXECUTIVE-MODE.) 

You can specify additional attributes for logical name tables when you create 
them. You can specify access control list (ACL) based protection for system 
logical name tables. For more information about ACL-based protection, see 
Chapter 7. Section 7.2.3.3 contains an example that shows how to specify an 
IDENTIFIER access control entry for a system logical name table. For more 
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information about other logical name table attributes, see the description of 
the CREATE/NAME—TABLE command in the VAX/VMS DCL Dictionary. 


4.7.5 Accessing Names in User-Defined Logical Name Tables 

After you create a logical name table, you can place logical names in the 
table, as shown below: 

$ DEFINE/TABLE=NEWTAB TESTDIR [JONES.TESTFILES] 

To use the name TESTDIR in a file specification, you need to create a new 
definition of the logical name LNM$FILE_DEV in your process directory 
logical name table to allow the system to search the table NEWTAB when 
logical name translation is performed. 

There are several ways to include your new table in the list of tables to be 
searched; the following example shows one method. 

$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV - 
_$ NEWTAB, LNMlPROCESS, LNM$JOB, LNM$GR0UP, LNM$SYSTEM 

In this example, a process-private version of LNM$FILE_DEV is defined to 
include your new table, NEWTAB, in the list of tables to be searched during 
logical name translation. Because the process-private version of LNM$FILE_ 
DEV will be used before the default system version, and because the logical 
name table NEWTAB is listed first, it will be searched before the process, job, 
group, or system table. 

Note that you must create LNM$FILE_DEV in the process directory table 
because table names or logical names that translate iteratively to table names 
must always be found in a directory table. 


4.7.6 Deleting Tables 

To delete a logical name table, you must delete it from the directory table 
where it is cataloged. For example, to delete the table NEWTAB from the 
process directory table, issue the command: 

$ DEASSIGN/TABLE=LNM$PROCESS_DIRECTORY NEWTAB 


4.8 Search Lists 


A search list is a logical name that has more than one equivalence string. For 
example: 

$ DEFINE LIST DISKI:[JONES.MEMOS],DISK1:[JONES.WORKFILES] 

$ SHOW LOGICAL LIST 

-LIST- = "DISKI:[JONES.MEMOS]" (LNM$PROCESS_TABLE) 

= "DISKI:[JONES.WORKFILES]" 

In this example, the logical name LIST is a search list because it has two 
equivalence strings. You can use a search list in any place you can use a 
logical name. 

When you use a logical name that is a search list, the system translates the 
logical name a number of times, using each equivalence string listed in the 
search list definition. The following example uses a search list. 
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$ DIRECTORY LIST:FILE.DAT 
Directory DISKI:[JONES.MEMOS] 

FILE.DAT;1 
FILE.DAT;2 
Total of 2 files. 

Directory DISKI:[JONES.WORKFILES] 

FILE.DAT;1 
Total of 1 file. 

Grand total of 2 directories, 3 files. 

The DIRECTORY command uses both equivalence strings for the search list 
LIST when searching for FILE.DAT. The display shows that there is a file 
named FILE.DAT in each directory. Note that the DIRECTORY command 
uses the equivalence strings for LIST in the order the strings were listed when 
LIST was defined. 

When you use a search list with a command that accepts wildcards in a 
file specification, the system forms file specifications using each equivalence 
string in the search list. The command performs its function on each file 
specification that identifies an existing file; other file specifications are ignored. 
For example, the DIRECTORY command in the previous example displayed 
listings for FILE.DAT in each directory in the search list. If FILE.DAT had 
existed in only one of the directories, then only one directory listing would 
have been displayed. If FILE.DAT had not existed in either directory, then an 
error message would have been displayed, indicating that file was not found. 
(If the error message specifies the file that was not found, the file specification 
displayed in the error message reflects the last equivalence string in the search 
list.) 

As shown in the following example, if you specify the TYPE command 
without the wildcard character in the version field, only the contents of the 
first match of the search string are displayed on the screen. 

$ TYPE LIST:FILE.DAT 

DISKI:[JONES.MEMOS]FILE.DAT;1 

When in disgrace with fortune and men's eyes 
I all alone beweep my outcaste state. 

If you specify the TYPE command with the wildcard character in the version 
field, the contents of all matches of the search list are displayed on the screen. 

$ TYPE LIST:FILE.DAT;* 

DISKI:[JONES.MEMOS]FILE.DAT;1 

When in disgrace with fortune and men's eyes 

I all alone beweep my outcaste state, 

DISKI:[JONES.MEMOS]FILE.DAT;2 

When in disgrace with fortune and men's eyes 

all alone beweep my outcaste state, 

And trouble deaf heaven with 

DISKI:[JONES.WORKFILES]FILE.DAT;1 

Let me not to the marriage of true minds 

admit impediments 

When you use a search list with a command that does not accept wildcards in 
a file specification, the system forms a file specification using each equivalence 
string in the search list, until a file specification for an existing file is found. 
The command performs its function only on the first existing file that 
is identified by the search list. The following example shows the RUN 
command, which does not accept wildcards. 
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$ DEFINE SYS$SYSTEM SYS$SYSR00T:[SYSEXE]. - 
_$ COMDISK:[SYSEXE] 

$ RUN SYS$SYSTEM:AVERAGE.EXE 

First, the system forms the file specification 

SYS$SYSROOT:[SYSEXE]AVERAGE.EXE, and searches for that file. If the 
file is found, then it is executed and the RUN command terminates. If the 
file is not found, then the system searches for the file AVERAGE.EXE in 
COMDISK:[SYSEXE]. If the file is found, then it is executed. If the file is not 
found, then an error message is displayed, indicating that the file could not 
be found. 

Note that the system displays an error message indicating a file could not be 
found only after it has used all equivalence strings in a search list. Then the 
system reports an error only on the last file it attempted to find. For example: 

$ TYPE SYS$SYSTEM:AVERAGE.FOR 

XTYPE-W-SEARCHFAIL, error searching for COMDISK:[SYSEXE]AVERAGE.FOR; 

-RMS-E-FNF, file not found 

The system reports an error finding COMDISK:[SYSEXE]AVERAGE.FOR; it 
does not report an error finding AVERAGE.FOR in SYS$SYSROOT:[SYSEXE]. 

You can include a node name in an equivalence string that is part of a search 
list. However, you cannot use a search list in the node portion of a file 
specification. The following search list includes a node name: 

$ DEFINE NODES NY::DISK4:, NJ::DISK7: 

You can use the search list as shown in the following command: 

$ DIRECTORY NODES:[JOHNSON] 

However, the next command will not work because it uses the search list 
incorrectly. 

$ DIRECTORY NODES::[JOHNSON] 


4.8.1 Using Search Lists with the SET DEFAULT Command 

When you specify a search list as the first part of the parameter for the SET 
DEFAULT command, the system assigns the search list name, untranslated, to 
SYS$DISK. (SYS$DISK is a logical name that translates to your default disk.) 
For example: 

$ SHOW DEFAULT 
DISK2: [JONES.SUB] 

$ DEFINE MY.FILES DISKI:[JONES]. DISK2:[JONES], DISK3: 

$ SET DEFAULT MY.FILES 
$ SHOW DEFAULT 

MY.FILES:[JONES.SUB] 

= DISKI:[JONES] 

= DISK2:[JONES] 

= DISK3:[JONES] 

At the beginning of this example, you can see that the default disk and 
directory are DISK2:[JONES.SUB]. Next, a search list is defined and the SET 
DEFAULT command uses the search list as its parameter. When you issue 
the SHOW DEFAULT command a second time, you can see that the default 
directory has not changed. However, the search list MY_FILES is displayed 
as the default device along with its equivalence strings. Note that the SHOW 
DEFAULT command displays the search list in the order in which the search 
list is evaluated by the system. 
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When you use the search list in a file specification, the search list is translated. 
If the search list contains both a device and a directory, then these are used to 
construct a complete file specification. If the search list contains only a device, 
then the original default directory is used. For example, the command: 

$ DIRECTORY MY_FILES:MEMO.LIS 

will give a directory listing for the following files: 

DISKI :[JONES]MEMO.LIS 
DISK2:[JONES]MEMO.LIS 
DISK3:[JONES.SUB]MEMO.LIS 

Note: When you specify a search list as the first part of a parameter for the 

SET DEFAULT command, each equivalence string in the search list must 
contain a device name. 


4.8.2 Search Order for Multiple Search Lists 

After you use the SET DEFAULT command with a search list, it is possible 
to have a file specification that contains more than one search list. When this 
occurs, the strings in the file name search list are used, while the first device 
name is held constant. After all the file name strings have been used with the 
first device name, then each of the file name strings is used with the second 
device name, and so on until each device has been used. 

The following example shows a file specification that has a search list in the 
file name and in the device name. 

$ DEFINE FILE CHAP1.RN0, CHAP2.RN0 
$ DEFINE DISK WORK1:[ROSE], W0RK2:[ROSE] 

$ SET DEFAULT DISK 
$ DIRECTORY FILE 
Directory W0RK1:[ROSE] 

CHAP1.RN0;2 CHAP2.RN0;1 

Total of 2 files. 

Directory W0RK2:[ROSE] 

CHAP1.RNO;1 CHAP2.RNO;1 

Total of 2 files. 

Grand total of 2 directories, 4 files. 

As shown in this example, the directory listing for each file name is given first 
for WORK1 :[ROSE], and second for WORK2:[ROSE]. 

You can also have iterative (nested) search lists, when one string in a search 
list translates to another search list. If this occurs, then the system will use 
each string in a sublist before continuing on to the next upper level string. 
For example: 

$ DEFINE NESTED FILE1.DAT, NEW.LIST, FILE2.DAT 
$ DEFINE NEW.LIST FILE3.DAT, FILE4.DAT 

The search order for the search list NESTED would be: FILE1.DAT, 
FILE3.DAT, FILE4.DAT, FILE2.DAT. 
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4.9 Logical Node Names 

A logical node name is a special type of logical name that can be used in 
place of a network node name, or in place of a node name and an access 
control string. For example, you can define a logical node name so you do 
not need to display the login information that is part of an access control 
string: 

$ DEFINE BOS "BOSTON""ADAMS JOHN""::" 

$ SHOW LOGICAL BOS 

BOS = "BOSTON"ADAMS JOHN"::" 

$ TYPE BOS::TEST.DAT 

When you issue the TYPE command to access a file on the remote node 
BOSTON, you can use the logical node name BOS. This example also shows 
the use of quotation marks in a DEFINE command; to enter quotation marks, 
you must enclose the equivalence string in quotation marks, and you must 
use double quotation marks in the places where you want quotation marks to 
appear. 

The rules for using logical node names are described below. 

A logical node name can contain up to 15 characters. The equivalence string 
that is equated to the logical node name must end with a double colon (::). If 
the equivalence string does not end in a double colon, then the logical name 
is not interpreted as a logical node name. For example: 

$ DEFINE REM "DALLAS""JONES HARRY""::USE1:" 

$ TYPE REM:STATS.DAT 

The logical name REM is equated to a node name and a device name; REM is 
not a logical node name because it contains more than the node specification 
and the equivalence string does not end in a double colon. When you use 
the logical name REM in a file specification, follow it with a single colon. 
REM is translated to its equivalence string, which contains a node name, an 
access control string, and a device name. When the translation is complete, 
the TYPE command displays the file: 

DALLAS"JONES password"::USE1:STATS.DAT 

Note: You should not place a DEFINE command that includes any password in 
a file such as your LOGIN.COM file. If other users read the file, they will 
see any password. 

A logical node name is translated at the local node. After the logical node 
name is translated, the rest of the file specification is parsed at the local 
node to determine whether the syntax is valid. However, logical names 
used as device names are not translated at the local node. Therefore, a file 
specification can contain a logical node name that is translated at your local 
node, and can also contain a logical device name that is translated at the 
remote node. For example: 

$ DEFINE NYC NEWYRK:: 

$ TYPE NYC::DOCD$:[PERKINS]TERM_PAPER.DAT 

The logical node name NYC is translated at the local node but the device 
name (DOCD$:) is translated at the remote node (NEWYRK). You must use 
a double colon in the DEFINE command because you are defining a logical 
node name; you must use a double colon in the TYPE command because 
you are using the logical node name NYC in the node position of the file 
specification. 



4-20 





Logical Names 




You can specify an access control string with a logical node name when you 
perform network file operations. This access control string will override an 
access control string that is provided in the equivalence string for the logical 
node name. Therefore, you can define a logical node name that contains a 
default access control string, but you can override the access control string 
when you want. For example: 

$ DEFINE BOS "BOSTON""ADAMS JOHN""::" 

$ TYPE BOS"REVERE PAUL"::RIDE.DAT 

In this example, the access control string "REVERE PAUL" overrides the 
access control string provided in the equivalence string. 

Logical node names are translated iteratively; after a logical node name is 
translated, the new node name becomes a candidate for logical node name 
translation. (Iterative translation is described in Section 4.6.1.) For example: 

$ DEFINE SYSMAN NODE::SYS$MANAGER: 

$ DEFINE NODE "ALPHA""DOE JANE""::" 

$ TYPE SYSMAN:SYLOGIN.COM 

When the file specification SYSMAN:SYLOGIN.COM is translated, the logical 
name SYSMAN is translated to NODE::SYS$MANAGER:, its equivalence 
string. Because translation is iterative, the equivalence string is examined to 
see if it contains a logical name; it contains the logical node name NODE. 
The logical node name NODE is translated to ALPHA"DOE JANE"::, its 
equivalence string. Therefore, the TYPE command displays the file: 

ALPHA"DOE JANE"::SYS$MANAGER:SYLOGIN.COM 

Note that the logical device name SYS$MANAGER is not translated at the 
local node; it is translated at the remote node ALPHA. 

When a logical node name is translated iteratively, the access control 
information in the logical node name that is first translated overrides 
subsequent access control information. For example: 

$ DEFINE TORONTO "TRNT0""TEST RESULTS""::" 

$ DEFINE TEST1 "TORONTO""TEST 1001""::DBA1:" 

$ TYPE TEST1:PR0C.DAT 

In the above example, the logical name TEST1 translates to TORONTO"TEST 
1001"::DBA1:. TORONTO is a logical node name, so iterative translation 
occurs. However, the access control string provided by the DEFINE TEST1 
logical name assignment overrides the access control string provided in the 
DEFINE TORONTO logical node name assignment. Therefore the TYPE 
command displays the file: 

TRNT0"TEST 1001"::DBA1:PR0C.DAT 

Logical node names that are prefixed by an underscore character are not 
candidates for logical name translation. However, the underscore character is 
not considered part of the node name. 
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4.10 


Logical Names for Process-Permanent Files 

Process-permanent files are files that can remain open for the life of your 
process. By default, DCL creates the following process-permanent files for 
you when you log in: 


SYS$COMMAND 


SYSSERROR 

SYS$INPUT 

SYSSOUTPUT 


The initial file from which DCL reads input. (A file from 
which DCL reads input is called an input stream.) The 
command interpreter uses SYS$COMMAND to “remember" 
the original input stream. 

The default file to which DCL writes error messages 
generated by warnings, errors and severe errors. 

The default file from which DCL reads input. 

The default file to which DCL writes output. (A file to 
which DCL writes output is called an output stream.) 


Table 4-6 shows the equivalence strings for your default process permanent 
files in each of the DCL command modes. 


Table 4-6 Equivalence Strings for Default Process Logical 
Names 


Logical Name 

Interactive 

Batch 

Equivalence String 
Command Procedure 

SYS$COMMAND 

Terminal© 

Disk© 

Terminal 

SYSSINPUT 

Terminal 

Disk 

Disk 

SYSSERROR 

Terminal 

Log file© 

Terminal 

SYSSOUTPUT 

Terminal 

Log file 

Terminal 


O Terminal = Device name of your terminal 
© Disk = Device name of initial default device 
© Log file = Batch job log file 

You can use the logical names for process permanent files when you specify 
files in commands. For example, to place input data in the command stream 
for a command or program, you can specify an input file as SYS$INPUT. The 
following example shows a FORTRAN command that could be executed in a 
batch job: 

$ FORTRAN/OBJECT=WEATHER SYS$INPUT: 

When this command is executed, the compiler reads the input file from the 
data lines following the FORTRAN command in the batch job command 
procedure. 

The /OBJECT=WEATHER qualifier provides the compiler with a default file 
name for the output files: it creates WEATHER.OBJ and WEATHER.LIS. To 
request that the listing file be written to the batch job output log file, you 
could specify the following: 

$ FORTRAN/OBJECT=WEATHER/LIST=SYS$OUTPUT SYS$INPUT: 

The compiler creates the file WEATHER.OBJ and prints the listing in the 
batch job output log. 
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4.10.1 Redefining SYSSINPUT 

You can redefine SYS$INPUT so that an image will obtain input from a 
file other than the default input stream. For example, to edit a file from a 
command procedure, redefine SYSSINPUT so that the editor will obtain input 
from the terminal, rather than from the default input stream (the command 
procedure file) as shown in the following example: 

$ EDIT.FILE: 

$ DEFINE/USER.MODE SYS$INPUT SYSSCOMMAND 
$ EDIT MYFILE.DAT 
$ PRINT MYFILE.DAT 


In this example, SYSSINPUT is temporarily redefined as SYSSCOMMAND. 
(SYSSCOMMAND refers to the terminal, the initial input stream when you 
logged in.) The user mode definition is in effect for the duration of the next 
image, so the editor accepts input from the terminal. When the editor is 
through executing, subsequent commands accept input from the default input 
stream, which, in a command procedure, is the command procedure file. 

Note that if you redefine SYSSINPUT, DCL will ignore your definition and 
will always obtain input from the default input stream. However, images will 
use the user-defined definition for SYSSINPUT. 


4.10.2 Redefining SYS$OUTPUT 

You can redefine SYSSOUTPUT to redirect output from your default device 
to another file. When you redefine SYSSOUTPUT, the system opens a file 
with the name you specify in the logical name assignment. When you define 
SYSSOUTPUT, all subsequent output is directed to the new file, not to the 
default definition of SYSSOUTPUT. 

When you redefine SYSSOUTPUT to redirect output from DCL commands 
that are executed within the command interpreter, the following conditions 
must be met. You must create the new logical name definition in supervisor 
mode, and must place the name in the process logical name table. Also, 
you must specify only one equivalence string, and you cannot specify any 
attributes for the new logical name. The following example shows a valid 
definition for SYSSOUTPUT: 

$ DEFINE SYSSOUTPUT MYFILE.LIS 

After this command is issued, DCL output is written to MYFILE.LIS, not to 
the terminal. 

Note that you can redefine SYSSOUTPUT in user mode to redirect output 
from images. However, DCL output will still be sent to the default output 
file. 

When you log in, the system creates two logical names called SYSSOUTPUT. 
One name is created in executive mode; the other name is created in 
supervisor mode. You can supersede the supervisor mode logical name 
by redefining SYSSOUTPUT. If you deassign the supervisor mode name, then 
the system redefines SYSSOUTPUT in supervisor mode, using the executive 
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mode equivalence string. You cannot deassign the executive mode name. For 
example: 

$ DEFINE SYS$OUTPUT TEMP.DAT 
$ SHOW LOGICAL SYS$OUTPUT 
$ SHOW TIME 
$ DEASSIGN SYSSOUTPUT 
$ TYPE TEMP.DAT 

”SYS$OUTPUT” * "DISKI:" (LNM$PROCESS_TABLE) 

27-JAN-1986 13:26:53 

First, SYS$OUTPUT is redefined (in supervisor mode) to the file TEMP.DAT. 
When SYS$OUTPUT is redefined, output from DCL and from images is 
directed to the file TEMP.DAT. Therefore, the output from the SHOW 
LOGICAL command (an image) and from the SHOW TIME command 
(a command that is executed within DCL) is sent to TEMP.DAT. When you 
deassign SYS$OUTPUT, the system closes the file TEMP.DAT and redefines 
SYS$OUTPUT (in supervisor mode) to your terminal. Therefore, when you 
issue the TYPE command, the file is displayed on your terminal. 

Note that when you redefine SYS$OUTPUT to a file, the logical name 
contains only the device portion of the file specification, even though 
the output is directed to the file you specify. In this example, when 
SYS$OUTPUT was redefined, the equivalence string contained the device 
name DISKI:, not the full file specification. 

If the system cannot open the file you specify when you redefine 
SYS$OUTPUT, an error message is displayed. 

Note that after you redefine SYS$OUTPUT, most commands direct output to 
the existing version of the file. However, certain commands will create a new 
version of the file before they write output. 


4.10.3 Redefining SYS$ERROR 

You can redefine SYS$ERROR to direct error messages to a specified file. 
However, if you redefine SYS$ERROR so it is different from SYS$OUTPUT 
(or if you redefine SYS$OUTPUT without also redefining SYS$ERROR), DCL 
commands will send informational, warning, error, and severe error messages 
to both SYS$ERROR and SYS$OUTPUT. Therefore, you will receive these 
messages twice—once in the file indicated by the definition of SYS$ERROR, 
and once in the file indicated by SYS$OUTPUT. Success messages will be 
sent only to the file indicated by SYS$OUTPUT. 

Note that if you redefine SYS$ERROR, and then run an image that references 
SYS$ERROR, the image will send error messages only to the file indicated 
by SYS$ERROR—even if SYS$ERROR is different from SYS$OUTPUT. 

Only DCL commands and images using standard VAX/VMS error display 
mechanisms send error messages to both SYS$ERROR and SYS$OUTPUT 
when these files are different. 

To suppress error messages completely, use the SET MESSAGE command. 
For example: 

$ SET MESSAGE/NOFACILITY /NOIDENTIFICATION - 
_$ /NOSEVERITY /NOTEXT 
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4.10.4 Redefining SYS$COMMAND 


Although you can redefine SYS$COMMAND, DCL will ignore your definition 
and will always use the default definition for your initial default stream. 
However, if you execute an image that references SYS$COMMAND, the 
image will use your new definition. 
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A symbol is a name to which you assign a character string or integer value. 
When you use a symbol in a DCL expression, DCL replaces the symbol 
name with its value. An expression is a value or a group of values that are 
evaluated; the result of the expression is assigned to a symbol. 

There are many ways you can use symbols and expressions in DCL command 
lines. For example, you can do the following: 

• Equate symbols to command strings, and use the symbols as command 
synonyms. 

• Use symbols as variables in DCL expressions. Symbols are often used as 
variables in command procedures. 

• Use symbols with commands such as READ, WRITE, and INQUIRE to 
refer to data records. 

• Use symbols to pass parameters to command procedures. 

• Use symbols to define foreign commands. 

This chapter describes the rules for creating symbols and writing expressions. 
Chapter 6 describes the rules DCL uses to substitute values for symbols in 
expressions and command lines. 


5.1 Symbol Definition 

To define a symbol, use the Assignment Statement ( = ) command. For 
example: 

$ COUNT = 1 

$ PROMPT = "Enter your name" 

The left side of the assignment statement defines the symbol name; the right 
side of the assignment statement contains an expression. When a symbol is 
created, DCL evaluates the expression and assigns the result to the symbol. 

If the expression is evaluated as an integer, then the symbol has an integer 
value. If the expression is evaluated as a character string, then the symbol 
has a string value. 

In the above examples, the symbol COUNT has an integer value because the 
expression (1) evaluates to an integer. The symbol PROMPT has a string 
value because the expression (Enter your name) evaluates to a character 
string. Note that you must enclose a character string in quotation marks 
when it is used in an expression. 

A symbol name can contain 1 to 255 characters. You must begin a symbol 
name with a letter (A through Z), an underscore, or a dollar sign. After the 
first character, the name can contain any alphanumeric characters from the 
DEC Multinational Character Set, underscores, and dollar signs. 
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To display the value of a symbol, use the SHOW SYMBOL command. For 
example: 

t SHOW SYMBOL COUNT 

COUNT =1 Hex = 00000001 Octal = 00000000001 

t SHOW SYMBOL PROMPT 

PROMPT = "Enter your name" 

To delete a symbol, use the DELETE/SYMBOL command. 


5.2 Symbol Types 

Symbols can be either local or global. Local symbols are available to the 
current command level and to command procedures executed from the 
current command level; global symbols are accessible at all command levels. 

Global and local symbols are stored in symbol tables. DCL maintains a local 
symbol table for each active command level; a local table is deleted when 
its associated command level terminates. However, DCL maintains only one 
global symbol table for the duration of a process. 


5.2.1 Local Symbols 

DCL places local symbols in the local symbol table for the current command 
level. To define a local symbol, use a single equal sign in the assignment 
statement. For example: 

* TEST = 15 

A local symbol exists as long as the command level at which it is defined 
remains active, unless the symbol is specifically deleted. 

In addition to the local symbols that you create, DCL creates eight local 
symbols whenever you create a new command level by executing a command 
procedure, using the CALL command, or submitting a batch job. These 
symbols, named PI, P2, and so on through P8, are used for passing 
parameters. If parameters are passed to the command procedure, they 
are equated to the special symbols in the local symbol table. Otherwise PI 
through P8 are defined as null character strings. 


5.2.2 Global Symbols 

DCL places global symbols in the global symbol table. To define a global 
symbol, use two equal signs in the assignment statement. For example: 

$ RESULT == 50 

A global symbol exists for the duration of the process, unless the symbol 
is specifically deleted, or treated as undefined by issuing the command SET 
SYMBOL/SCOPE=NOGLOB AL. 

DCL maintains three reserved global symbols in addition to the global 
symbols you create. Following is a list of these symbols. 
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SSTATUS 

SSEVERITY 


SRESTART 


The condition code returned by the most recently executed 
command. $STATUS conforms to the format of a VAX/VMS 
message code. 

The severity level of the condition code returned by the most 
recently executed command. SSEVERITY, which is equal to the 
three low-order bits of SSTATUS, can have the following values: 
0 Warning 

1 Success 

2 Error 

3 Information 

4 Severe (fatal) error 

Has the value TRUE if a batch job was restarted after it was 
interrupted by a system crash. Otherwise, SRESTART has the 
value FALSE. 


5.2.3 Symbol Search Order 

When the command interpreter determines the value of a symbol, it searches 
symbol tables in the following order: 

1 The local symbol table for the current command level 

2 Local symbol tables for each previous command level, searching 
backwards from the current level 

3 The global symbol table 

By default, the SHOW SYMBOL command uses the same order of search to 
locate symbol definitions, that is, it searches the local symbol tables and then 
the global symbol table to locate a specified symbol name. For example: 

$ TEST = “HELLO" 

$ TEST == "GOODBYE" 

$ SHOW SYMBOL TEST 

TEST = "HELLO" 

The DELETE/SYMBOL command, however, uses a different method when 
searching for symbols to be deleted. By default, DELETE/SYMBOL deletes 
symbols from the local symbol table. If you want to delete a global symbol, 
you must use the /GLOBAL qualifier. 


5.3 Abbreviating Symbol Names 

You can use abbreviated forms of symbols if you define them using the 
abbreviation character, the asterisk. The following example shows how to 
create a local symbol that can be abbreviated: 

$ M*AIL = "MAIL" 

The VAX/VMS Mail Utility will be executed whenever the following versions 
of the symbolic name are used: 

M 

MA 

MAI 

MAIL 
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Generally, you can use abbreviated symbol definitions in any situation that 

allows a symbol to be used. However, there are some restrictions: 

• You cannot abbreviate symbols that involve substring replacement. 

• When you define a symbol that includes the abbreviation character, 
existing symbols may be deleted. If an existing symbol exactly matches 
the new symbol at or past the abbreviation punctuation character, the new 
symbol replaces the existing symbol. 

• If an existing symbol is defined with the abbreviation character, DCL 
issues an error message if you try to add a new symbol whose name 
exactly matches the abbreviated symbol at or past the asterisk. However, 
if the new symbol name exactly matches the existing symbol name, the 
new symbol replaces the old symbol. 


5.4 Special-Purpose String Assignments 

An optional format for assigning a character string value to a symbol name is: 

symbol-name : = [=] character string 

This form of the assignment statement is called a special-purpose string 
assignment, because you cannot use this format to assign an integer value to 
a symbol. 

With this form of string assignment statement, you do not need to place 
quotation marks around the character string. However, character string 
values are automatically converted to uppercase. Also, any leading and 
trailing spaces and tabs are removed, and multiple spaces and tabs between 
characters are compressed to a single space. For example: 

$ KILL := delete sys$batch /entry= 

$ SHOW SYMBOL KILL 

KILL = "DELETE SYS$BATCH /ENTRY*" 

$ KILL 132 

In this example, the command string assigned to the symbol KILL is converted 
to uppercase, and the multiple spaces between the command parameters are 
reduced to a single space. 

If you want to prohibit uppercase conversion and retain required space and 
tab characters in a string, you must place quotation marks around the string, 
for example: 

$ NAME := "job search" 

$ SHOW SYMBOL NAME 

NAME * "job search" 

You can continue a String Assignment (:=) statement on more than one line. 
For example: 

$ LONG.NAME := THIS_IS_A_VERY_LONG_SYMBOL- 
_$ _NAME_VALUE_CONTINUED_MORE_THAN_ONE_LINE 

See the description of the := (String Assignment) statement in the VAX/VMS 
DCL Dictionary for more information on special-purpose string assignments. 
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5.5 Values Used in Expressions 

The following sections describe values that can be used in expressions. 
Expressions can contain character strings, integers, lexical functions, symbols, 
or combinations of these values. The values in expressions are called 
operands. If an expression contains more than one operand, the operands 
are connected by operators that specify the operations to be performed. 


5.5.1 Character Strings 

A character string can contain any characters that can be printed. When you 
use character strings in expressions, you must enclose them in quotation 
marks. To include quotation marks within a string, type two consecutive 
quotation marks. For example: 

$ PROMPT * "Type ""YES"" or ""NO""" 

$ SHOW SYMBOL PROMPT 

PROMPT = "Type "YES" or "NO"" 

To make the symbol assignment in the preceding example, you must use 
two sets of quotation marks around the words YES and NO. Also, you must 
enclose the entire character string with quotes because the string is used in 
an expression. Note that alphabetic case and spaces are preserved when the 
symbol assignment is made. 

To continue a character string over two lines, use a plus sign (for string 
concatenation) and a hyphen (for continuation). For example: 

$ HEAD = "MONTHLY REPORT ♦ - 
_$ " APRIL 1986" 

$ SHOW SYMBOL HEAD 

HEAD = "MONTHLY REPORT -- APRIL 1986" 

You can also concatenate several symbols to create a long character string. 
Note that you do not place quotation marks around symbols when you use 
them in expressions: 

$ D0G2A = "No tag, light brown, 30 lbs." 

$ D0G2B = " — looks part beagle" 

$ D0G2 = D0G2A + D0G2B 


5.5.2 Integers 


Unless you specify an alternate radix, the command interpreter treats all 
numeric values as decimal integers. You can specify a radix by using the 
radix operator (%X for hexadecimal, %D for decimal, or %0 for octal). 
There cannot be any blanks between a radix operator and a value. When 
you specify a value in either hexadecimal or octal, the command interpreter 
converts the value to a decimal integer. 

The following examples show integers that are used in expressions. Do not 
place quotation marks around integers. 

$ count = 10 

$ SHOW SYMBOL COUNT 

COUNT = 10 Hex = 0000000k Octal = 00000000012 
$ NUM = 7.010 
$ SHOW SYMBOL NUM 

NUM = 8 Hex = 00000008 Octal = 00000000010 
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5.5.3 Lexical Functions 

Lexical functions return information about a requested item. You invoke a 
lexical function by typing its name (which always begins with F$) and its 
argument list: 

F$lunction-name(args[,...]) 

The argument list must be enclosed in parentheses. You can use lexical 
functions in expressions in the same way you would normally use character 
strings, integers, and symbols. The following example uses the F$LENGTH 
function in an expression. The F$LENGTH function returns an integer that 
specifies the length of the string; the returned value is assigned to the symbol 
LEN. 

* LEN = F$LENGTH("The cat jumped over the moon.") 

* SHOW SYMBOL LEN 

LEN = 29 Hex = OOOOOOID Octal = 000035 

When you use lexical functions in expressions, do not enclose them in 
quotation marks. Also, you must specify the arguments for lexical functions 
as expressions. Therefore, if an argument contains a character string, you 
must enclose the character string in quotation marks. (If an argument contains 
an integer, a symbol, or another lexical function, do not enclose these values 
in quotation marks.) In the above example, the F$LENGTH function is not 
enclosed in quotes, but the argument, a character string, is. 

The value and data type returned by a lexical function depend on the 
function. For complete descriptions of each lexical function, its required 
arguments, and its return values, see the section on Lexical Functions in the 
VAX/VMS DCL Dictionary . 


5.5.4 Symbols 

When you use a symbol in an expression, the symbol's value is automatically 
substituted for the symbol. For example: 

* COUNT = 3 

* NEW.COUNT = COUNT + 1 

* SHOW SYMBOL NEW.COUNT 

NEW.COUNT =4 Hex = 00000004 Octal * 00000000004 

After a symbol is defined, it can be interpreted as character string or integer 
data, depending on the context in which it is used. For example, suppose a 
symbol, COUNT, is assigned the integer value 4 in an arithmetic assignment 
statement: 

* COUNT = 4 

Then the value of COUNT can be used in other assignment statements as 
shown in the following examples. 
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$ TOTAL = COUNT + 1 An arithmetic assignment statement that 

adds the value of COUNT to the value 
1 and equates the result to the symbol 
TOTAL, which now equals 5. 

$ SYMBOL := P'COUNT' a string assignment statement that 

converts the value of COUNT to a string, 
and appends the string value of COUNT 
to the character P. SYMBOL now equals 
the string P4. Note that when you use 
a symbol in a string assignment (:=) 
statement, the symbol's value is not 
automatically substituted. Therefore you 
must use apostrophes to request symbol 
substitution. 

If you define a null character string value for a symbol, that symbol has a 

value of 0 when it is used in an arithmetic context. For example: 

$ a = ,,M 

$ b = 2 

$ C = A + B 

After these statements are executed, the symbol C has a value of 2. 


5.6 Expression Evaluation 

An expression can evaluate to either an integer or a string value, depending 
on the types of values used in the expression and the operations used to 
manipulate them. Table 5-1 summarizes the rules for determining whether 
an expression will evaluate to a string or to an integer. 


Table 5-1 Rules for Determining Expression Modes 


Expression 

Mode and 
Resultant 

Value Type 

Integer value 

Integer 

String value 

String 

Integer lexical function 

Integer 

String lexical function 

String 

Integer symbol 

Integer 

String symbol 

String 

+, -, or .NOT. any value 

Integer 

Any value .AND. or .OR. any value 

Integer 

String + or—string 

String 

Integer + or—any value 

Integer 

Any value + or—integer 

Integer 

Any value * or / any value 

Integer 

Any value (string comparison) any value 

Integer 

Any value (arithmetic comparison) any value 

Integer 
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In this table, if "any value" is a character string value, it is converted to 
an integer value before the operation is performed, except for the string 
comparison expression. In string comparison expressions, if "any value" is 
an integer, it is converted to a string value before the string comparison is 
performed. 

As shown in Table 5-1, in certain cases character strings are converted to 
integers. For example, to evaluate the expression: 

$ SUM = "B M + 7 

DCL must convert the string "B" to an integer. The following sections describe 
how DCL performs value type conversion. 


5.6.1 String to Integer Conversion 

Character strings are converted to integers in the following ways: 

• Strings containing numbers are converted to their integer values. For 
example, the string "45" is converted to the integer 45. 

• Alphabetic strings are converted to the integer 1 if the string begins with 
T, t, Y, or y, or to the integer 0 if the string begins with any other letter. 
For example, the string "ELIZABETH" is converted to the integer 0. 

The following examples show how string values are converted to integer 
values. 


String 

—> 

Resulting Integer 

"123" 

—> 

123 

" 12XY" 

—> 

0 (False) 

"Test" 

—> 

1 (True) 

"hello" 

—> 

0 (False) 


In most expressions that contain both integer and string values, DCL 
automatically converts the string values to integers before performing the 
operation. However, when performing string comparisons, DCL converts 
integers to strings before performing the comparison. 


5.6.2 Integer to String Conversion 

When integers are converted to character strings, the resulting string contains 
numbers that correspond to the integer value as shown in this example. 


Integer 

—> 

Resulting String 

123 

—> 

"123" 

1 

—> 

"1" 

0 

—> 

“0" 


In string comparison operations, DCL converts integer values to strings before 
performing the comparison. 
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5.6.3 


Explicit Value Type Conversion 

Two lexical functions, F$INTEGER and F$STRING, enable you to explicitly 
change the context of a particular expression. The F$INTEGER lexical 
function converts a string expression to an integer value, while the F$STRING 
function converts an integer expression to a string value. 

To determine the current value type of a symbol, you can use the F$TYPE 
lexical function. 



5.7 


Types of Expressions 

Expressions can evaluate to either character strings or to integers; these types 
of expressions are discussed in the following sections. 



5.7.1 Character String Expressions 

A character string expression is an expression that evaluates to a string value. 
The format of an assignment statement that equates a symbol name to a 
character string expression is as follows: 

symbol-name =[*] string-expression 

A string expression can contain character strings, lexical functions that 
evaluate to character strings, or symbols that have string values. A string 
expression can also contain groups of string operands that are connected by 
operators to perform string operations. (See Section 5.8.1.) 

The following examples show character string expressions that are equated to 
symbols. 

$ NAME = "MYFILE.DAT" 

$ TEMP = "TEMPORARY FILE CREATED" 

$ TOPIC - "THE" ♦ TEMP 
$ COUNT * FISTRING(65) 

$ OUTPUTMESSAGE = "Beginning..." 

$ TOTAL = "NUMBER OF FILES ■ " ♦ FISTRING(16) 

$ SUBTOTAL = TOTAL 

Some of these expressions contain a single value that is a character string, 
symbol name, or a lexical function. Notice, however, that some string 
expressions contain character strings, symbols, and lexical functions that 
are connected with string operators. In order for string operations to occur, 
both operands must have character string values. 

The following expression contains the operands "THE " (a character string) 
and TEMP (a symbol equated to a string value). 

$ TOPIC = "THE " + TEMP 

The plus sign operator in this example concatenates the two operands. The 
string is evaluated and the resulting character string is assigned to the symbol 
TOPIC. So, if the symbol TEMP were assigned the value 'TEMPORARY FILE 
CREATED", the value for the symbol TOPIC would be "THE TEMPORARY 
FILE CREATED". Note that when you use a character string in a string 
expression, you must place quotation marks around the string. However, 
when you use a symbol in a string expression, you do not use quotation 
marks. 
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5.7.2 Integer Expressions 

An integer expression is an expression that evaluates to an integer. The 
format of an assignment that equates a symbol name to an integer expression 
is as follows: 

symbol-name = [=] integer-expression 

An integer expression can contain integers, lexical functions that evaluate to 
integers, or symbols that have integer values. An integer expression can also 
contain groups of integer or string operands that are connected by arithmetic 
operators, logical operators, and comparison operators. 

The following examples show integer expressions whose results are assigned 
to symbols. 

$ COUNT * 1 

$ VALUE = y.xic 

$ SUM *1+7-4/3+10 


5.8 Operators in Expressions 

Table 5-2 lists the valid operators you can use in forming expressions, 
and defines the order of precedence of evaluation. Note that logical and 
comparison operators must be preceded and terminated by a period (.) 
with no intervening blanks. You can type any number of blanks or tabs 
between operators and operands. For example, the following expressions are 
equivalent: 

A.EQS.B 
A .EQS. B 

Each operator (except .NOT. and the unary plus or minus signs) must have 
an operand on each side. 

When you specify more than one operation in an expression, the operations 
are performed in the order of precedence shown in Table 5-2. Operators at 
the top of the table are performed before operators at the bottom. Operations 
of the same precedence are performed from left to right, as they appear in the 
command string. 

Use parentheses to override the order in which operators are evaluated. 
Expressions within parentheses are evaluated first. 


Table 5-2 Order of Precedence of Operators in Expressions 


Operator 

Precedence 

Description 

+ 

7 

Indicates a positive number 

- 

7 

Indicates a negative number 

• 

6 

Multiplies two numbers 

/ 

6 

Divides two numbers 

+ 

5 

Adds two numbers or concatenates two character 
strings 

- 

5 

Subtracts two numbers or reduces two strings 

EQS. 

4 

Tests if two character strings are equal 
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Table 5- 

-2 (Cont.) 

Order of Precedence of Operators in 
Expressions 

Operator 

Precedence Description 

.GES. 

4 

Tests if first string is greater than or equal to 
second 

.GTS. 

4 

Tests if first string is greater than second 

.LES. 

4 

Tests if first string is less than or equal to second 

.LTS. 

4 

Tests if first string is less than second 

.NES. 

4 

Tests if two strings are not equal 

.EQ. 

4 

Tests if two numbers are equal 

.GE. 

4 

Tests if first number is greater than or equal to 
second 

.GT. 

4 

Tests if first number is greater than second 

.LE. 

4 

Tests if first number is less than or equal to 
second 

.LT. 

4 

Tests if first number is less than second 

.NE. 

4 

Tests if two numbers are not equal 

.NOT. 

3 

Logically negates a number 

.AND. 

2 

Combines two numbers with a logical AND 

.OR. 

1 

Combines two numbers with a logical OR 


5.8.1 String Operations 

Use string operations to concatenate or reduce strings. The result of a string 
operation is a character string value. You can use the following operators to 
perform string operations. 


Operator 

Meaning 

+ 

String concatentaion 

- 

String reduction 


In order for string concatenation or reduction to occur, both operands must 
be character string expressions. Otherwise, the string will be converted to an 
integer and the result will be an integer. 

In a string concatenation operation, the plus sign operator concatenates two 
character strings to form a single character string. In a string reduction 
operation, the minus sign operator subtracts one character string from 
another. If the string following the minus sign in a string reduction operation 
occurs more than once in the preceding string, only the first occurrence is 
removed. 

Following are some examples of string operations. 

A = "MYFILE" + “.MEM” "MYFILE.MEM” 

B = “FILENAME.MEM” - “FILE” “NAME.MEM” 

C = “LISTING.LIS” - "LIS” “TING.LIS" 

D = “MIS” + C "MISTING.LIS” 
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5.8.2 Arithmetic Operations 

Use arithmetic operators to perform calculations in integer expressions. The 
result of an arithmetic operation is an integer. You can use the following 
arithmetic operators: 

+ Arithmetic sum 

- Arithmetic difference 

+ Arithmetic unary plus 

- Arithmetic unary negate 

* Arithmetic product 

/ Arithmetic division (integer quotient) 

The result of an arithmetic operation is an integer. Operands in arithmetic 
operations are integer expressions. If you specify a string value as an operand, 
it is converted to an integer value before the operation is performed. 

In arithmetic operations, all nondecimal (specified by radix operators) values 
are converted to integer values before the operation is performed. All 
arithmetic is integer arithmetic; that is, all fractional values are truncated. 

Following are some examples of arithmetic operations. 


Expression 

Result 

A = 5 + 10 / 2 

A = 10 

B=5*3-4*6/2 

CO 

ii 

CO 

C = 5 * (6 - 4) - 8 / (2 - 1) 

C = 2 

D = %X50 

D = 80 

E = %X10 + 5 

E = 21 

F = 6 / 4 

F = 1 

G = -5 + 4 

G = -1 


5.8.3 Logical Operations 

Use logical operators to perform logical functions on integer values or to 
construct complicated expressions. The result of a logical operation is an 
integer. You can use the following logical operators: 

.OR. Logical OR 

AND. Logical AND 

.NOT. Logical complement 

Operands for logical operations are integer expressions. If you specify a 
character string value as an operand, it is converted to an integer value before 
the operation is performed. 

Following are some examples of logical expressions. 
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Expression 

Value of Symbol 

A = 3 .OR. 5 

A = 7 

B = 3 .AND. 5 

B = 1 

C = .NOT. 3 

1 

ii 

o 

D = 3 + 4 .AND. 2 + 4 

D = 6 


Note that logical operators can be used in a logical as well as an arithmetic 
sense. An integer has a logical value of true (1) if it is odd (that is, the low- 
order bit is 1). A character string has a logical value of true (1) if the first 
character is an upper- or lowercase T or Y. 

An integer has a logical value of false (0) if it is even (that is, the low-order 
bit is 0). A character string has a logical value of false if the first character is 
not an upper- or lowercase T or Y. 

For example: 
a = yjciooo .or. y.xoooi 

This expression performs a logical OR operation on two values. The resulting 
value of the symbol A is %X1001, or 4097. Note that one of the two values 
in the OR expression (%X0001) is logically true; the other value (%X1000) 
is logically false. The resulting value of A (%1001) is logically true. An 
arithmetic OR always yields a logical as well as an arithmetic result. 


5.8.4 Arithmetic Comparisons 

Use arithmetic comparison operators to compare integer values. The result of 
an arithmetic comparison is an integer. You can use the following operators 
in arithmetic comparisons: 

.EQ. Arithmetic equal to 

.GE. Arithmetic greater than or equal to 

.GT. Arithmetic greater than 

.LE. Arithmetic less than or equal to 

.LT. Arithmetic less than 

.NE. Arithmetic not equal to 


Operands in arithmetic comparisons are integer expressions. If you specify a 
character string value as an operand, it is converted to an integer value before 
the comparison is performed. (If a character string begins with an upper- or 
lowercase T or Y, it is converted to the integer 1. If a string begins with any 
other letter, it is converted to the integer 0. If a string contains numbers that 
form a valid integer, then the string is converted to its integer equivalent.) 

If the result of an arithmetic comparison is true, the expression has a value 
of 1; if the result of the comparison is false, the expression has a value of 0. 
Following are some examples. 
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Expression 

Value of Expression 

1.LE.2 

1 (true) 

1.GT.2 

0 (false) 

1 + 3 .EQ. 2 + 5 

0 (false) 

"TRUE".EQ. 1 

1 (true) 

“FALSE".EQ.O 

1 (true) 

"123".EQ.123 

1 (true) 


5.8.5 String Comparisons 

Use string comparison operators to compare character strings. Character 
string comparison is based on the binary values of the ASCII characters in 
the string. The ASCII characters and their hexadecimal values are listed in 
Table 5-3. The result of a string comparison is the integer 0 or 1. You can 
use the following operators in string comparisons: 

.EQS. String equal to 

.GES. String greater than or equal to 

.GTS. String greater than 

.LES. String less than or equal to 

.LTS. String less than 

.NES. String not equal to 


The following rules apply to character string comparisons: 

• The comparison is on a character-by-character basis; the comparison 
terminates as soon as two characters do not match. 

• If one string is longer than the other, the shorter string is padded on the 
right with nulls (an ASCII value of %X00) before the comparison is made. 
Note that a null has a lower numeric value than any of the alphabetic or 
numeric characters. 

• Lowercase letters have higher numeric values than uppercase letters. 

If the result of a comparison is true, the expression is given a value of 1; if 
the comparison is false, the expression is given a value of 0. Some examples 
are listed next. 


Expression 

Result 

Explanation 

“MAYBE".LTS."maybe" 

1 (true) 

The expression is true because 
the ASCII value of "M" is less 



than "m." 

"ABCD".LTS."EFG" 

1 (true) 

The expression is true because 
the ASCII value of "A" is less than 
“E." 
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Expression 

Result 

Explanation 

"YES".GTS.“YESS” 

0 (false) 

The expression is false because 
the ASCII value of a null character 
is less than the ASCII value of 
"S". 

"AAB".GTS. “AAA" 

1 (true) 

The expression is true because 
the ASCII value of "B" is greater 
than “A". 

"TRUE”.EQS. 1 

0 (false) 

DCL converts the integer 1 to the 
string "1” before comparing the 
ASCII value of "T" to the ASCII 
value of "1". 

“FALSE”.EQS.O 

0 (false) 

DCL converts the integer 0 to 
the string "0” before making the 
comparison. 

" 123".EQS. 123 

1 (true) 

DCL converts the integer 123 to 
the string "123” before making 
the comparison. 


Operands in string comparisons are string expressions. If you specify an 
integer value as an operand, it is converted to a string before the comparison 
is performed. 

If you do not enclose a character string in quotation marks, the command 
interpreter assumes the string is a symbol name and issues an error message 
if the symbol is not defined. 
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Table 5-3 DEC Multinational Character Set 


HEX 

Code 

ASCII 
Char . 

HEX 

Code 

ASCII 
Char . 

HEX 

Code 

ASCII 
Char . 

HEX 

Code 

ASCII 
Char . 

00 

NUL 

20 

SP 

40 

@ 

60 

V 

01 

SOH 

21 

i 

41 

A 

61 

a 

02 

STX 

22 

H 

42 

B 

62 

b 

03 

ETX 

23 

# 

43 

C 

63 

c 

04 

EOT 

24 

$ 

44 

D 

64 

d 

05 

ENQ 

25 

% 

45 

E 

65 

e 

06 

ACK 

26 

& 

46 

F 

66 

f 

07 

BEL 

27 

i 

47 

G 

67 

g 

08 

BS 

28 

( 

48 

H 

68 

h 

09 

HT 

29 

) 

49 

I 

69 

i 

0A 

LF 

2A 

★ 

4A 

J 

6A 

j 

0B 

VT 

2B 

+ 

4B 

K 

6B 

k 

OC 

FF 

2C 

t 

4C 

L 

6C 

1 

0D 

CR 

2D 

- 

4D 

M 

6D 

m 

0E 

SO 

2E 

. 

4E 

N 

6E 

n 

OF 

SI 

2F 

/ 

4F 

O 

6F 

o 

10 

DLE 

30 

0 

50 

P 

70 

P 

11 

DC 1 

31 

1 

51 

Q 

71 

q 

12 

DC 2 

32 

2 

52 

R 

72 

r 

13 

DC 3 

33 

3 

53 

S 

73 

s 

14 

DC 4 

34 

4 

54 

T 

74 

t 

15 

NAK 

35 

5 

55 

U 

75 

u 

16 

SYN 

36 

6 

56 

V 

76 

v 

17 

ETB 

37 

7 

57 

W 

77 

w 

18 

CAN 

38 

8 

58 

X 

78 

X 

19 

EM 

39 

9 

59 

Y 

79 

y 

1A 

SUB 

3A 

: 

5A 

Z 

7A 

z 

IB 

ESC 

3B 

? 

5B 

[ 

7B 

{ 

1C 

FS 

3C 

< 

5C 

\ 

7C 

1 

ID 

GS 

3D 

= 

5D 

] 

7D 

} 

IE 

RS 

3E 

> 

5E 

A 

7E 


IF 

US 

3F 

? 

5F 

— 

7F 

DEL 
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Replacing Substrings in Character String Symbol Values 

A special format of the character string assignment statement allows you to 
replace data within a defined substring of a value. This format is as follows: 

symbol-name[offset.size]:= replacement-string 

The offset is the position of the substring relative to the first character in the 
string, and the size is the length of the substring. 

The square brackets are required notation, and no spaces are allowed between 
the symbol name and the left bracket. You can specify integer expressions for 
the offset and the size. Integer values can be in the range of 0 through 768. 
The replacement-string must be a character string. 
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This type of assignment statement evaluates the current value of symbol, and 
then replaces a specified string of characters with the specified character string 
value. For example: 

$ A := ABCDEF 
$ A[0,3] := DEF 

The first assignment statement above gives the symbol name A the value 
ABCDEF. The second assignment statement specifies that the value DEF 
replaces three characters in the value of A, beginning at an offset of 0 
from the beginning of the string. The result is that the value of A becomes 
DEFDEF. 

The symbol name you specify can be undefined initially. The assignment 
statement creates the symbol name and, if necessary, provides leading or 
trailing spaces in the symbol value if necessary. For example: 

$ B[4,3]: = GHI 

If the symbol named B does not have a value when this assignment statement 
is executed, the resulting value of B is " GHI", that is, B has four leading 
spaces before the characters GHI. You can use this format to create a blank 
line of any number of characters. For example: 

$ LINE[0,80]:= ” M 

This assignment statement gives the symbol named LINE a value of 80 blank 
spaces. The following example shows how you can use this assignment 
statement syntax to align data in columns for output: 

$ RECORD[0,20] := "Programmer" 

$ RECORD[25.15 ]:= "File Name" 

These two assignment statements construct a value for the symbol RECORD. 
The first statement fills in the first 20 columns of the value; the second 
statement fills in columns 26 through 40. Columns 20 through 24 contain 
blanks. 

Figure 5-1 illustrates some applications of string substitutions using offsets. 

In the figure, substitutions change the current value of the symbol FILENAME 
from its initial assignment, MYFILE.DAT, to TRTEST.DAT; 1. Then the current 
value of the symbol COMMAND is combined with the string TRTEST.DAT; 1 
to produce a new assignment for COMMAND. 


5.10 Arithmetic Overlays 

A special format of the assignment statement can be used to perform binary 
overlays of the current symbol value. This format is as follows: 

$ symbol-name[bit-position,size]= replacement-expression 

The bit-position is the location relative to bit 0 at which the overlay is to 
occur, and size is the number of bits to be overlaid. The square brackets are 
required notation, and no spaces are allowed between the symbol name and 
the left bracket. The bit-position and size are integer expressions. Literal 
values are assumed to be decimal. The replacement-expression must be an 
integer expression. 

This type of assignment statement evaluates the current value of the symbol 
name, and then replaces the specified number of bits with the value on the 
right-hand side of the assignment statement. This form of an assignment 
statement can store a maximum of 32 bits at a time. You can use this 
statement to equate a symbol name to a binary value. For example: 
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Figure 5-1 Replacing Character Strings in Assignment 
Statements 


Interactive Assignment 

$ FILENAME:=MYFILE.DAT 


Resulting Symbol Value 


Comments 


MYFILE*DAT The result is the initial value of symbol 

FILENAME 


$ FILENAMECO>2 3:= TR 


TRF I LE ♦ DAT Two characters starting at offset 0 are overlaid 


$ FILENAME[2»43:=TESTING.LIS TRTEST♦DAT 


When the string value is longer than the char¬ 
acter count the value is truncated to the count 


FILENAME:10 >23 : = 5 1 


TRTEST ♦ DAT ; 1 When the length of the string is equal to the 

value of the offset, the string is appended to 
the current value 


COMMAND:= T Y PE 


TYPE This is the initial value of the symbol command 


$ C0MMANDC5 >133 : = 'FILENAME ' TYPE TRTEST . DAT ? 1 Appends a space and the current value of 

FILENAME to the TYPE command verb. 

ZK-818-82 


$ BELL[0,32]*%X07 

This statement gives the symbol named BELL a value equivalent to a 
hexadecimal 7. The hexadecimal 7 is interpreted as the ASCII code for 
the bell character (CTRL/G) on a terminal, because the symbol BELL was 
previously undefined. 

When symbols are either undefined or defined as strings, the result of the 
arithmetic overlay is a string. Otherwise the result is an integer. Thus, if 
the symbol BELL had been previously defined as an integer value, then the 
assignment statement in the above example would have assigned the integer 
value 7 to the symbol BELL. 
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5.11 Using Symbols to Define a Foreign Command 

The command interpreter allows you to define foreign commands. A foreign 
command is a symbol that you use to invoke an image. Although a foreign 
command is not known to the command interpreter, you can execute the 
command by entering a command string. 

An alternative to using the foreign command is to define new commands 
with the Command Definition Utility. See the VAX/VMS Command Definition 
Utility Reference Manual for more information. 


5.11.1 Defining a Foreign Command 

Use either of the following assignment statement formats to define a foreign 
command: 

$ symbol-name :=[=] $image-file-spec 
$ symbol-name =[=] n $image-:file-spec" 

symbol-name 

The name by which you want to invoke the image. 

$image-file-spec 

The file specification of the image to be executed. The default device and 
directory name is SYS$SYSTEM, the default file type is EXE, and the default 
file version number is the highest version. 

The dollar sign ($) preceding image-file-spec is required. 

After you have defined a foreign command as shown above, the request to 
execute the image is implicit in the symbol definition. When this symbol- 
name is specified as the first token, or item, in a command, the command 
interpreter executes the specified image. For example: 

$ PROCESS := IDB1:[MALCOLM.PROG]CREPROCES 
$ PROCESS 

In this example, the symbol-name PROCESS is defined as a foreign 
command. When PROCESS is specified as the first token in a command, 
you can specify any data following it. For example: 

$ PROCESS ORION 

This command string passes the string ORION to the executing image, but 
the image must obtain the parameter string. The image must also perform 
any parsing or evaluation of the command string because the command 
interpreter does not parse the line. 

Note that during command input, the command interpreter performs all 
symbol substitution requested by apostrophes in the command string. Thus, 
if you use symbols or lexical functions preceded by apostrophes to specify 
parameters in a command string, symbol substitution occurs before the 
command string is passed to the program. 

You can use an abbreviated form of a foreign command if you use the 
abbreviation character (the asterisk) when you define the foreign command. 
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5.11.2 Obtaining a Parameter String from the Command Interpreter 

To obtain a parameter string passed with a foreign command, you can call 
the Run-Time Library routine LIB$GET_FOREIGN. See the VAX/VMS Run¬ 
Time Library Routines Reference Manual for more information on using the 
LIB$GET__FOREIGN routine in your programs. 





6 Symbol Substitution 


When it is processing a command string, the command interpreter performs 
symbol substitution by replacing symbol names in the command string with 
their current values. This chapter describes how the command interpreter 
performs symbol substitution. 


6.1 Automatic Symbol Substitution 

The command interpreter assumes, in certain contexts, that a string of 
characters beginning with an alphabetic character is a symbol name or a 
lexical function. In these contexts, substitution is automatic and you do not 
need to use substitution operators. If you use apostrophes around a symbol 
that would automatically be evaluated, the results may be different than you 
expect. 

The command interpreter automatically evaluates symbols and lexical 
functions in the following positions: 

• On the right side of an = or == assignment statement (but not a 
:= or :== assignment statement) 

• In an argument for a lexical function 

• In the brackets on the left-hand side of an assignment statement when 
you are performing substring replacement or arithmetic overlays 

• In a DEPOSIT, EXAMINE, IF, or WRITE command 

• At the beginning of the line when the symbol is not followed by an equal 
sign or a colon 

It is important to note that, in any of these contexts, the command interpreter 
assumes that any string of characters beginning with an alphabetic character 
is a symbol name and that any string of characters beginning with a numeral 
or with the radix operator (%) is a literal numeric value. The following 
examples show situations where automatic symbol substitution occurs. 

This example shows automatic symbol substitution on the right side of an 
assignment statement. 

$ count = 5 
$ TOTAL = COUNT + 1 

In the second line of this example, the value for COUNT is automatically 
substituted. The result of the expression (6) is assigned to the symbol 
TOTAL. 

The next example shows symbol substitution in an argument for a lexical 
function. 

$ LINE = "Haven't we met before?" 

$ LEN = F$LENGTH(LINE) + 5 
$ SHOW SYMBOL LEN 

LEN = 27 Hex = 0000001B Octal = 000033 
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The string value for the symbol LINE is automatically substituted when LINE 
is used as an argument for the F$LENGTH function. Also, the F$LENGTH 
function is automatically evaluated because it is on the right side of an 
assignment statement, and the resulting value is used in the expression 
F$LENGTH(LINE) + 5. 

The next example shows symbol substitution after an IF command. 

| IF A .EQ. B THEN WRITE SYS$OUTPUT "DONE" 

The IF command assumes that both A and B are symbol names and uses their 
current values to test their equality. 

The last example shows symbol substitution at the beginning of a command 
line. 

$ PDEL = M DELETE SYS$PRINT/ENTRY=" 

| PDEL 181 
$ PDEL (182,183) 

In this example, the symbol PDEL is equated to the command string DELETE 
SYS$PRINT/ENTRY=. You can now use PDEL at the beginning of a line as a 
command synonym. In the second and third lines, the command interpreter 
automatically replaces PDEL with its current value and executes the resulting 
command string. 


6.2 Substitution Operators 

You can use symbols in places other than where they will be evaluated 
automatically. However, you must use a substitution operator to request 
symbol substitution. DCL accepts two substitution operators: 

• Apostrophe ( 7 ) 

• Ampersand (&) 


6.2.1 Using Apostrophes as Substitution Operators 

The apostrophe is the normal substitution operator. You must use the 
apostrophe to request symbol substitution when you use a symbol name 
in place of a command parameter or qualifier (unless you are supplying a 
parameter for a command that automatically performs symbol substitution). 
For example: 

$ type -filename* 

In this example, the string FILENAME is a symbol name used as a parameter 
for the TYPE command; the apostrophes enclosing the string indicate to the 
command interpreter that FILENAME is a symbol name and not a literal 
string. (If you had not used apostrophes, the command would have looked 
for a file called FILENAME.LIS.) 

You must also use the apostrophe operator to request symbol substitution 
when you use a symbol on the right-hand side of a := (String Assignment) 
statement. 

| NAME := REPORT 
| FILE := -NAME'.DAT 
$ SHOW SYMBOL FILE 
FILE = "REPORT.DAT" 
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In this example, the value for NAME is substituted, forming the string 
"REPORT.DAT". 


6.2.1.1 Concatenation of Symbol Names with the Apostrophe Operator 

When you use symbols in places where you must request symbol substitution, 
you can concatenate two or more symbol names, as shown in the following 
example: 

* NAME = "MYFILE" 

$ TYPE = ".TST" 

* PRINT 'NAME''TYPE' 

If this example is executed, the PRINT command queues a copy of 
MYFILE.TST. Note that you must delimit symbol names by placing 
apostrophes around each symbol for which you are requesting substitution. 


6.2.1.2 Substitution Within Character Strings 

Within character strings enclosed in quotation marks, you can request symbol 
substitution by placing two apostrophes before the symbol name and one 
apostrophe following it. For example: 

* PROMPT.STRING = “Creating file "FILENAME* .TST" 

If the current value of the symbol named FILENAME is WIDGET, the symbol 
name PROMPT_STRING is given the following value: 

Creating file WIDGET.TST 

Note that when using apostrophes to request symbol substitution, you cannot 
continue the line (with the hyphen continuation character) in the middle of 
the value that is being substituted. 


6.2.2 Using Ampersands as Substitution Operators 

In addition to the apostrophe, the command interpreter recognizes a special 
substitution operator, the ampersand. The difference between these two 
operators is the time when the substitution occurs. Symbols preceded by 
apostrophes are substituted during the first phase of command processing; 
symbols preceded by ampersands are substituted during the second phase of 
command processing. (See Section 6.3.1 for more information on the phases 
of command processing.) 

In many usages, the apostrophe and ampersand substitution operators are 
functionally equivalent. For example, the following two commands would 
have the same result if the string FILENAME is equated to a character string 
value. 

$ TYPE 'FILENAME' 

* TYPE ^FILENAME 

In the first command, the command interpreter replaces the string FILENAME 
with its current value during the first phase of command processing 
(scanning). The second command replaces the string FILENAME with its 
current value during the second phase of command processing (parsing). 

The following examples show how the results can vary, depending on 
whether you use an apostrophe or an ampersand as the substitution operator. 

* B = "MYFILE.DAT" 

* A = "ftB" 

* SHOW SYMBOL A 

A = "ftB" 

* TYPE 'A' 
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In the preceding example, the file MYFILE.DAT is displayed. However, if you 
then add a second assignment statement for B, such as: 

$ B = "NEWFILE.TMP" 

$ TYPE 'A* 

the file NEWFILE.TMP is displayed. 

In the first example, the second assignment statement equates the symbol 
name A to the current value of B, using the ampersand operator. When the 
assignment is made, the value of B is not substituted because the ampersand 
does not cause symbol substitution when it is used inside quotation marks. 
(This is shown in the SHOW SYMBOL A command.) However, the first 
TYPE 'A' command displays the file MYFILE.DAT. This occurs because the 
command interpreter scans the TYPE command line and substitutes the 
value &B for A. Next, it parses the line and substitutes the MYFILE.DAT for 
the symbol &B. Note that when you redefine B, the result of the TYPE 'A' 
command changes. 

The following restrictions apply to the use of the ampersand: 

• You cannot use an ampersand within a character string to request symbol 
substitution; that is, an ampersand must follow a delimiter (any blank or 
special character). 

• You cannot use ampersands to request substitution within character strings 
enclosed in quotation marks. 

• You cannot use ampersands to concatenate two or more symbol names for 
which you are requesting substitution. 

• When you use the ampersand to request symbol substitution, place the 
ampersand before the symbol name; do not also terminate the symbol 
name with an ampersand. 

Ampersands are most effective as substitution operators when they are used 
with apostrophes to affect the order in which substitution is performed, as 
described in the following examples. 

The following command string uses the syntax: 

$ PRINT &P'COUNT' 

This causes the command interpreter to first replace the symbol COUNT with 
its value. If the value of COUNT is 1, the resulting string is: 

$ PRINT API 

During the second phase of command processing (parsing), the ampersand 
causes the command interpreter to replace the symbol PI with its value. 

Note what happens if the token is specified as follows: 

$ PRINT 'P''COUNT 1 

In this example, the command interpreter, during initial scanning of the 
command, performs normal left-to-right substitution. It attempts to replace 
the separate tokens P and COUNT. Because P is not a defined symbol, only 
COUNT is replaced. The PRINT command string is thus: 

PRINT 1 

The action the command interpreter takes when a symbol is undefined 
depends on the context of the command. For more information, see 
Section 6.4. 
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6.3 Repetitive and Iterative Substitution 

Symbol substitution can be either repetitive or iterative when substitution 
occurs more than once during the processing of a single command string. 
Repetitive substitution results when more than one type of substitution occurs 
in a single command string. Iterative substitution occurs when the command 
interpreter examines a substituted value to see if the value itself is a symbol. 

Iterative substitution occurs only when symbols delimited by the apostrophe 
operator are translated during the first phase of command processing. 


6.3.1 Symbol Substitution During the Three Phases of Command 
Processing 

The command interpreter performs symbol substitution in three phases of 
command processing. These phases are as follows: 

1 Command input scanning. During this phase, also called the lexical input 
phase, the command interpreter reads the command input and replaces 
all tokens that are preceded with apostrophes (or double apostrophes, 
for strings within quotation marks). Symbols that are preceded with 
apostrophes are translated iteratively, as described in Section 6.3.2. 
Symbols (preceded with double apostrophes) within character strings 
are not translated iteratively. 

2 Command parsing. During this phase, the command interpreter analyzes 
the command string. DCL determines whether the first value on the 
command line is a symbol used as a command synonym and, if it 

is, replaces the symbol with its current value. DCL also performs all 
substitutions requested with ampersands. Symbol substitution during the 
command parsing phase is not iterative. 

3 Expression evaluation. During this phase, the command interpreter 
replaces symbols during the actual execution of a command (such as the 
IF command). This substitution is not iterative. 

Note that the command interpreter does not scan any lines in a command 
procedure that are read as input data by commands or programs executed 
within the procedure. Therefore, the command interpreter does not perform 
substitution within these data lines. For example: 

$ RUN AVERAGE 

55 

57 

9999 

The program AVERAGE reads its input from SYS$INPUT, that is, the 
command input stream. The lines 55, 57, and 9999 are data lines for the 
program AVERAGE. These data lines are never read by the command 
interpreter. Thus, you cannot use symbol names in lines that are read as 
input to programs. 


6-5 






Symbol Substitution 


6.3.2 Iterative Substitution Using Apostrophes 

When you use an apostrophe to request symbol substitution, the command 
interpreter performs iterative substitution during the first (scanning) phase of 
symbol substitution. Iterative substitution is performed from left to right in 
the command string. 

Substitution using apostrophes is not iterative, however, when values are 
substituted for symbols within strings that are enclosed in quotation marks. 
For example: 

$ SYMBOL = "5" 

$ A = "'SYMBOL'» 

$ B = 'A' 

$ SHOW SYMBOL B 
B = "5" 

$ B = '" 'A'” 

$ SHOW SYMBOL B 
B = "'SYMBOL'" 

After the statement B = 'A' the resulting value of the symbol B is 5. This 
result is achieved in the following steps: 

1 The symbol name A is enclosed in apostrophes, so it is replaced with its 
current value ('SYMBOL'). 

2 Because this value ('SYMBOL') is also enclosed in apostrophes, the 
command interpreter replaces the value SYMBOL with its current value 
(5). 

3 Because this value (5) has no apostrophes, the command input scanning 
phase is complete. No further substitution is required during the 
command parsing or expression evalution phases. Therefore, 5 is the 
final value given to the symbol name B. 

Note, however, what happens when you define B as: 

$ B = ""A'" 

In this case, B has the value 'SYMBOL'. The symbol name A is replaced only 
once, because substitution is not iterative within character strings enclosed in 
quotation marks. 


6.3.3 Iterative Substitution Using Command Synonyms 

The command interpreter performs iterative substitution automatically only 
when an apostrophe is in the command string. In some cases, you may want 
to nest command synonym definitions, as follows: 

$ COMMAND = "TYPE A.B" 


$ EXEC = "'COMMAND"' 


$ EXEC 

In this example, when the command synonym EXEC is processed, the 
command interpreter performs substitution only once. The resulting string is 
'COMMAND'; the command interpreter issues an error message because it 
cannot detect a command on the line. 
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This error occurs because, during the first phase of command processing, no 
substitution is performed (the string EXEC is not delimited by apostrophes). 
During the second phase, the string 'COMMAND' is substituted for EXEC 
because EXEC is the first value on the command line. This substitution is not 
iterative; therefore, even though 'COMMAND' is delimited by apostrophes, 
no additional substitution is performed. 

To correctly use the command synonym EXEC, you must enclose it in 
apostrophes, as shown below: 

* ’EXEC* 

In this command line, the symbol EXEC is evaluated during the first phase 
of command processing because it is delimited by apostrophes. Because this 
substitution is iterative, the resulting value ('COMMAND') is also evaluated 
and the string TYPE A.B is substituted. No further substitution is required 
during the second or third phases of command processing. 


6.3.4 Iterative Substitution in Expressions 

When the command interpreter analyzes an expression in a command, any 
symbols specified in the expression are replaced only once; iteration is not 
automatic. You can, however, force iteration by using an apostrophe or an 
ampersand in the expression. When you design a procedure to force iteration 
in this way, you must remember: 

• The command interpreter performs all substitutions requested by 
apostrophes and ampersands before the command string is executed. 

• Commands that automatically perform symbol substitution do so after the 
command string has been processed by the command interpreter. 

The following example illustrates iterative substitution in an IF command. 

$ IF P 1 COUNT' .EQS. "" THEN GOTO END 

When the command interpreter scans this input line, it replaces the symbol 
name COUNT with its current value. If the current value of COUNT is 1, the 
command string, after scanning, is as follows: 

IF PI .EQS. "" THEN GOTO END 

Because this string has no apostrophes, the command interpreter does not 
perform any more substitution. However, when the IF command executes, it 
automatically evaluates the symbol name PI and replaces it with its current 
value. 

Note, however, that if the token resulting from substitution by the command 
interpreter is not a valid symbol name, the command will fail because a 
symbol is undefined. For example: 

* FILENAME = "A.B" 

* IF 'FILENAME' .NES. "" THEN TYPE 'FILENAME' 

When the command interpreter processes this command string, it replaces 
the symbol name FILENAME with its current value. After substitution, the 
command string is as follows: 

IF A.B .NES. "" THEN TYPE A.B 
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When the IF command executes the command line, A.B is not a valid symbol 
and an error occurs. For this IF command to be processed correctly, you must 
omit the apostrophes, as follows: 

$ IF FILENAME .NES. "" THEN TYPE 'FILENAME' 

Apostrophes are required in the TYPE command string because the command 
interpreter does not automatically replace symbols used as parameters for the 
TYPE command. 


6.4 Substitution of Undefined Symbols 

If a symbol is not defined when it is used in a command string, the command 
interpreter either issues an error message or replaces the symbol with a null 
string, depending on the context. The rules are as follows: 

• During command input scanning and during command parsing, the 
command interpreter replaces all undefined symbols that are preceded by 
apostrophes or ampersands with null strings. 

• During expression evaluation, the command interpreter issues a warning 
message and does not complete command processing. 

These rules are illustrated in the following examples. 

The first example shows how the command interpreter processes an 
undefined symbol that is preceded by an apostrophe: 

$ FILE := MYFILE'FILE_TYPE' 

$ SHOW SYMBOL FILE 
FILE = "MYFILE" 

$ PRINT 'FILE' 

When the symbol FILE is created, the symbol FILE_TYPE is replaced with 
its current value. If FILE—TYPE is not defined, the command interpreter 
replaces FILE—TYPE with a null string. In the above example, the command 
interpreter would give the symbol FILE a value of MYFILE. 

Note that, to the command interpreter, a null string can be a meaningful 
construct. In the above example, the absence of a file type in the file 
specification for the PRINT command causes the PRINT command to use 
the default file type of LIS. 

In the following arithmetic assignment statement, the expression is evaluated 
during the expression evaluation phase of command processing. Therefore, 
the command interpreter does not perform the statement if there are 
undefined symbols. For example: 

$ A = 1 
$ C = A + B 

7.DCL-W-UNDSYM, undefined symbol - check validity and spelling 


In this example, the symbol B is undefined so the command interpreter cannot 
evaluate the expression. 
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The operating system controls access to objects such as files, directories, 
devices, system logical name tables, and global sections through two 
mechanisms: 

• UlC-based protection 

• Access control lists 

Each user of the system has a user identification code (UIC) defined in 
the system user authorization file (UAF). Each system object also has an 
associated UIC, which is the UIC of its owner, and a protection code that 
defines who is allowed what type of access. The relationship between the 
UIC of the user and the UIC of the object controls access to the object. 

A system object can have an associated access control list (ACL) that explictly 
specifies the access that a particular user or groups of users are allowed. The 
system objects for which ACL-based protection may be specified are files, 
directories, devices, logical name tables, and global sections. In an ACL, users 
are specified by identifiers. There are three types of identifiers: 

• UICs that uniquely identify each user on the system 

• System-defined identifiers that describe certain types of users (BATCH, 
NETWORK, DIALUP, INTERACTIVE, LOCAL, REMOTE) 

• General identifiers defined by the system manager in the system rights 
database that identify groups of users on the system 

When determining whether a user is allowed access to a particular object, the 
system follows these steps: 

1 If an object has an associated ACL, the system uses the ACL to determine 
whether the user has access to the object. If the ACL does not explicitly 
allow or refuse the user access, then the system uses UlC-based protection 
to determine access. If the ACL denies access, the system uses the 
SYSTEM and OWNER fields of the UlC-based protection to determine 
access. 

Note that if the owner is zero (no owner), and the object has an ACL, 
access is determined by the ACL alone. 

2 If an object does not have an associated ACL, the system uses UlC-based 
protection to determine access. Access is granted or denied on the basis of 
the relationship between the object's UIC and the user's UIC. 

3 The GRPPRV, SYSPRV, READ ALL, and BYPASS privileges amplify the 
holder's access to objects in certain circumstances. 
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7.1 UlC-Based Protection 

UIC-based protection is determined by an owner UIC and a protection code. 
UlC-based protection controls access to practically all objects in the system: 
files, directories, volumes, devices, mailboxes, common event flag clusters, 
global sections, logical name tables, and queues. A volume is the entity that 
exists when a medium is mounted on a device. For example, disk packs and 
reels of magnetic tape are called volumes when they are mounted on disk 
and tape drives. For disk volumes, the system provides protection at the 
file, directory, and volume levels. For tape volumes, the system provides 
protection only at the volume level. 

Volume protection for disks and tapes is coded into the home block of the 
disk or tape. See the descriptions of the INITIALIZE, MOUNT, and SET 
VOLUME commands for more information about setting volume protection 
characteristics for disks and tapes. 

The system also provides protection for record-oriented devices such as 
terminals, line printers, mailboxes, and special-purpose devices. See the 
description of the SET PROTECTION/DEVICE command for information on 
how to apply protection to record-oriented devices. 


7.1.1 Specifying User Identification Codes 

A UIC has two formats: numeric and alphanumeric. When a DCL command 
requires a UIC specification, you can use either format. Regardless of the 
format you use, the system translates a UIC to a 32-bit value that represents 
a group number and a member number; the high-order 16 bits contain the 
group number and the low-order 16 bits contain the member number. 

A UIC in numeric format contains a group number and a member number in 
the format 

[group,member] 

The brackets are required in the UIC specification. The group number is an 
octal number in the range of 0 through 37776; the member number is an octal 
number in the range of 0 through 177776. You can omit leading zeros when 
you are specifying group and member numbers. 

A UIC in alphanumeric format consists of a member name and, optionally, a 
group name in the format: 

[member] 

[group,member] 

The brackets are required in the UIC specification. The group and member 
names can each contain up to 31 alphanumeric characters and must contain 
at least one alphabetic character. The names can include the characters A 
through Z, dollar signs ($) and underscores (_), and the numbers 0 
through 9. 

The member part of an alphanumeric UIC is equated to both the group and 
member parts of a numeric UIC in the system rights database. Therefore, 
each member name must be unique for each user on the system. You cannot 
have a [GROUP1JONES] and [GROUP2JONES] on the same system, because 
JONES can have only one UIC associated with it. 

A group name is associated with the group portion of a UIC. When the 
system translates a named UIC that includes both a group and a member 
name, the system obtains the longword integer associated with the member. 
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The system manager assigns UICs to each user with the Authorize Utility 
(AUTHORIZE). Since an alphanumeric UIC is equated to a numeric UIC in 
the rights database, you can generally specify either format to refer to a user 
process. 

For example, the following are all valid UIC specifications for the user JONES: 

[ 360 , 031 ] 

[JONES] 

[GR0UP1,JONES] 


7.1.2 


How the System Determines Access 

When a user attempts to access an object, the user's UIC is compared to the 
owner UIC of the object. Depending on the relationship of the UICs, the user 
falls into one or more of these four categories. 


SYSTEM 


OWNER 

GROUP 

WORLD 


All users who have the system privilege (SYSPRV) or low group 
numbers, usually from 1 through 10 (octal). However, the exact 
range of system group numbers is determined by the system 
manager with the SYSGEN parameter MAXSYSGROUP, and may 
range as high as 37776 (octal). These group numbers are generally 
for system managers, system programmers, and operators. In 
addition, the SYSTEM protection field is used for those users with 
the user privilege GRPPRV whose UIC group matches the group of 
the object's owner. 

The user with the same UIC as the owner UIC of the object. 

All users, including the owner, who have the same group number in 
their UICs as the object owner. 

All users, including those in the first three categories. 


Figure 7-1 illustrates the relationships of these categories to each other. 
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Figure 7-1 Illustrating User Categories with a UIC of [100,100] 
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Each of these categories of user can be allowed or denied any of the following 
types of access: 


• READ 

• WRITE 

• EXECUTE 

• DELETE 


Control access is not included in this list because it is never specified in the 
standard UlC-based protection code. However, control access grants the 
accessor all the privileges of the object's actual owner; therefore, the user who 
acquires control access can change the protection and file characteristics, just 
as the owner can. Thus, users in the system or owner categories always have 
control access, while users in the group or world categories never receive 
control access. 

The protection code describes the categories of users who have access to an 
object, and the type of access that they have. For example, the protection 
code 


SYSTEM:RWED, OWNER:RWED, GROUP:RE, WORLD:RE 

specifies that users in the SYSTEM and OWNER categories have READ, 
WRITE, EXECUTE, and DELETE access. Users in the GROUP and WORLD 
categories have READ and EXECUTE access. 
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The following syntax rules apply to protection codes: 

• When you specify a protection code, you must abbreviate access types to 
one character. User categories can be entered in full or truncated to any 
number of characters. Separate each user category from its access types 
with a colon. If you specify more than one user category, separate the 
categories with commas and enclose the entire code in parentheses. 

• You can specify the user categories and access types in any order. If you 
omit an access type for a user category, that category of user is denied that 
type of access. If you want to deny all access to a user category, specify 
the user category but do not list any access types. Also, omit the colon 
after the user category when you are denying access to a category of users. 

• When you omit a user category from a protection code applied to one or 
more files or from a code specified for the default protection, the current 
access allowed that category of user remains unchanged. 

• When you omit a user category from a protection code applied to an entire 
volume, that category of user is denied all types of access, except when 
setting the protection for magnetic tape volumes. SYSTEM and OWNER 
always have access on magnetic tape volumes, regardless of the protection 
specified. 


For example, the following protection code allows the system all types of 
access, allows group members read access only, and prohibits all access by 
users in the world category. The code does not change the current access for 
the owner. 

$ SET PROTECTION(SYSTEM:RWED,GROUP:R,WORLD) DATAFILE.DAT 


7.1.3 How Privileges Affect Protection 

Four of the system privileges can affect the access a user actually receives, 
regardless of the access apparently dictated by the protection code of the 
user's category. These four privileges are SYSPRV, GRPPRV, READ ALL, 
and BYPASS. If a user holds any one of these privileges, the outcome of the 
protection check may be quite different from your initial expectation. 

The user with the SYSPRV privilege receives the access accorded to users in 
the SYSTEM category. 

The user with the GRPPRV privilege whose UIC group matches the group 
of the owner of the object receives the same access accorded to users in the 
SYSTEM category. 

The user with the BYPASS privilege receives all types of access to the object, 
regardless of its protection. 

The user with the READ ALL privilege receives READ and CONTROL access 
to the object, even if that access is denied by the protection. In addition, the 
user may receive any other access that is granted through the protection. 
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7.1.4 How the System Interprets a Protection Code 

To determine access to an object (such as a file or a device), the system uses 
the resource's protection code for each user category. The system checks user 
categories from the outermost category (WORLD) to the innermost category 
(SYSTEM). You can access a resource as soon as the system finds a user 
category that allows you access. To deny access to a user category, be sure to 
deny access to all outer categories. 

For example, the following protection code denies DELETE access to a file's 
owner: 

SYSTEM:RWED, OWNER:RW t GROUP:RW, WORLD:RWED 

However, you can still delete the file because you have DELETE access in the 
WORLD category, which applies to all users. 


7.1.5 Disk File Protection 

Each file on a disk has its own protection code. When applied to files, access 
types have the following meanings: 

READ The right to examine, print, or copy the file. 

WRITE The right to modify or to write to the file. 

EXECUTE The right to execute a file that contains an executable program 

image. 

DELETE The right to delete the file. 

Note that read access also implies execute access. Also note that to open a 
file for a write operation, you must have both read and write access, because 
the VAX/VMS operating system does not support write-only files. 

You can specify a protection code when you create a file. For example, you 
can use the /PROTECTION qualifier to define the protection for a file you 
create with the COPY command, as shown below: 

$ COPY USE1:[PAYDATA]PAYROLL.DAT PAYSORT.DAT - 
_$ /PROTECTION=(SYSTEM:RW,OWNER:RWED,GROUP:RW,WORLD) 

This COPY command copies a file from the device USE1 to your default disk 
directory. The protection code defines the protection for the newly created 
file PAYSORT.DAT as follows: users with system UICs can read and write to 
the file; you (the owner) have all types of access; other users in your group 
may read and write to the file; and all other users (the world) are permitted 
no access. 

You can also change the protection for an existing file with the SET 
PROTECTION command. For example: 

$ SET PROTECTION®(SYSTEM:RWE,OWNER:RWED,GROUP:RE,WORLD) - 
_$ PAYSORT.EXE 

If you do not define a protection code for a file when you create it, the system 
applies a default protection. If a version of the file already exists, protection 
is taken from the previous version of the file. For a new file, the protection is 
determined in one of two ways: 

• If the directory where the file is to be cataloged has an associated access 
control list that specifies the DEFAULT-PROTECTION entry, then the 
specified protection is used. 
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• If the directory does not have an associated access control list, then the 
default process protection is used. (The default process protection is 
established explicitly with the SET PROTECTION/DEFAULT command, 
or by default when you log in.) 

You can determine the current default protection by issuing the SHOW 
PROTECTION command: 

$ SHOW PROTECTION 

SYSTEM=RWED, OWNER=RWED, GROUP=RE. W0RLD=N0 ACCESS 

This response is your default protection. It indicates that system users and 
the owner have all types of access, that members of the owner's group have 
read and execute access, and that all other users (the world) have no access. 

You can change the default protection applied to files that you create during 
a terminal session with the SET PROTECTION/DEFAULT command. 

To determine the current protection associated with a specific file or files, use 
the /PROTECTION qualifier on the DIRECTORY command. For example: 

$ DIRECTORY/PROTECTION PERSONNEL.REC 

Directory USE1:[CRAMER] 

PERSONNEL.REC;5 (RWED,RWED,RW,R) 

Total o 1 1 file. 

Note: To protect a file completely, you must protect both the file itself and 
the directory in which the file is listed. If you have files that must be 
protected against unauthorized access, be sure to specify the proper 
protection both for the directories in which the files are listed and for the 
files themselves. 

A file that denies DELETE access can be removed from a directory if a user 
has READ and WRITE access to the directory. For example: 

$ RENAME [JONES]STATUS.RNO [SMITH]JUNK.XYZ 

The file STATUS.RNO has been renamed JUNK.XYZ in the directory [SMITH]. 
Although the file still exists, it is no longer cataloged in its owner's directory. 
Unless a directory and a file are both protected, processes that have write 
access to a directory can use the RENAME command to "delete" files from 
that directory even if the files themselves are protected against deletion. 


7.1.6 Directory File Protection 

Each directory file has a protection associated with it. The directory protection 
can override the protection of individual files in the directory. When applied 
to directories, access types have the following meanings: 

READ The right to examine, or list the directory file. 

WRITE The right to modify or write to the directory file 

EXECUTE The right to look up files in the directory if you explicitly specify the 
file name 

DELETE The right to delete the directory file 

READ access implies EXECUTE access. If you have READ access to a 
directory file, you can display the contents of the directory file with the 
DIRECTORY command. You can use wildcards (explicitly or implicitly). For 
example, if you have READ access to the directory [MALCOLM], you can 
issue the command 
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$ DIRECTORY [MALCOLM] 

and you will get a listing of the files contained in the [MALCOLM] directory. 
In addition, you can access any file cataloged in the directory unless the 
file's protection denies you access. However, if a directory denies you READ 
access, you cannot look up or access even those files in the directory that 
permit access to users in your group. Strictly speaking, the Files-11 structure 
is not hierarchical, and it is possible to access files without using the directory 
in which they are listed through suitable programming techniques. To 
guarantee protection, therefore, individual files should also be protected. 

WRITE access allows you to write to the directory file. You must have 
both READ and WRITE access to a directory in order to create files in that 
directory, to rename files or to perform any file operation that involves 
changes to the directory file. 

EXECUTE access has a special meaning when it is applied to directories. 
EXECUTE access allows you to use the DIRECTORY command to look up 
files that you can identify by name. In addition, you can access files in the 
directory that are not protected against users in your category if you do not 
perform an operation that modifies the directory file. However, you cannot 
list all the entries in the directory by using wildcards. 

For example, if you have EXECUTE access to the [MALCOLM] directory, and 
you issue the command 

$ DIRECTORY [MALCOLM] 

the system will respond with an error message and will not list the files in the 
[MALCOLM] directory. However, if you know that the file DATAFILE.DAT 
exists in the [MALCOLM] directory, you can issue the command 

$ DIRECTORY [MALCOLM]DATAFILE.DAT;0 

and the system will list the corresponding directory information. Therefore, 
EXECUTE access provides some, but not all, of the operations that READ 
provides. 

DELETE access allows you to delete a directory file. You must remove all 
entries from a directory file before you can delete it. When you create a 
directory file with the CREATE/DIRECTORY command, you do not, by 
default, get DELETE access. If you want to delete a directory file, you must 
use the SET PROTECTION command to explictly assign DELETE access to 
the OWNER category. 

To protect your files, you must make sure that they are adequately protected 
at both the directory and file level. 


7.1.7 Volume Protection 


When applied to volumes, access types have the following meanings: 


READ 

WRITE 

EXECUTE 

DELETE 


The right to examine, print, or copy files on a volume 
The right to modify or to write files on a volume 
The right to create files on the volume 
The right to delete files on the volume 


READ access implies EXECUTE access. 


7-8 





Protection 


Note: EXECUTE and DELETE access are not valid for magnetic tapes. Granting 
a category of users WRITE access to a magnetic tape volume automatically 
permits them to have READ access to the volume. 

Volume protection is determined when a volume is mounted; it can be 
defaulted from the device protection code or can be explicitly specified. 

(See the descriptions of the INITIALIZE and MOUNT commands for more 
information on setting volume protection when you mount a volume.) To 
change the protection of a disk volume, use the SET VOLUME command. 

The protection applied to a magnetic tape volume applies equally to all files 
on the volume. The operating system applies only read and write access 
restrictions with respect to magnetic tapes; execute and delete access are 
meaningless. Moreover, system users and the owner are always given both 
read and write access, regardless of what you specify in a protection code. 
Protection must be explicitly specified when a volume is initialized, or all 
users will have read and write access. If you give write access to the group 
or world, read access is also allowed. For magnetic tapes mounted with the 
/FOREIGN qualifier, system users and the owner are always given logical 
and physical I/O access in addition to read and write access, regardless of 
what you specify in the protection code. 

File protection on a given magnetic tape can be changed only if the tape is 
reinitialized. 


7.2 Access Control Lists 

The VAX/VMS operating system offers access control lists (ACLs) as an 
alternative means of protection for system objects. The system objects for 
which ACL-based protection may be specified are files, directories, devices, 
logical name tables, and global sections. Generally, this method is used in 
conjunction with the standard UlC-based protection as a way to fine-tune 
that protection. The ACL offers a way to match the specific access you want 
to grant or deny to specific users for each object. The basis of this method 
is a rights database that specifies identifiers, holders of those identifiers, and 
access control lists that associate the identifiers with the access to be granted 
or denied to them. This section describes this mechanism and explains how 
you can put it to use. 

The rights database is a file that associates users of the system with special 
names they are allowed to hold (called identifiers). Some identifiers represent 
the user names and UICs. Other identifiers are more general names that 
many users hold. The system manager or security manager maintains 
this rights database, adding and removing identifiers as needs change. 

By allowing groups of users to hold identifiers, the manager creates a 
different kind of group designation than the one used with the user's UIC. 
This alternative grouping permits each user to be a member of multiple 
overlapping groups. In addition, the types of access allowed to particular 
objects by the holders of an identifier can be more finely tailored. 

When you log in, the identifiers you hold in the rights database (including 
your UIC) are copied into a rights list that is part of your process. The rights 
list is the structure used by the VAX/VMS operating system to perform all 
protection checks. Additional identifiers may appear in your rights list; they 
were put there either by the VAX/VMS login software or by software specific 
to your installation. These identifiers represent various qualifications about 
your login, the state of the system, and so forth. 
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Identifiers are the means of specifying the users in an ACL. There are three 
types of identifiers: 


• UIC identifiers that depend on the user identification codes (UICs) that 
uniquely identify each user on the system 

• General identifiers that are defined by the security manager in the system 
rights database to identify groups of users on the system 

• System-defined identifiers that describe certain types of users (BATCH, 
NETWORK, DIALUP, INTERACTIVE, LOCAL, REMOTE) 


UIC identifiers conform to the specifications for UICs. 


A general identifier, defined in the system rights database, is an alphanumeric 
string of from 1 through 31 characters that must contain at least one 
alphabetic character. It can include the characters A through Z, dollar signs 
($) and underscores (_), as well as the numbers 0 through 9. Typical general 
identifiers, for example, might be STUDENT and PERSONNEL. 


The security manager creates and assigns the general identifiers and UICs to 
the system users with the Authorize Utility (AUTHORIZE). 


System-defined identifiers are automatically defined by the system when the 
rights database is created at system installation time. 


The following identifiers, which correspond directly with the login classes are 
system-defined identifiers. Listed with each are the access attempts associated 
with the identifier. 


BATCH 

NETWORK 

INTERACTIVE 

LOCAL 

DIALUP 

REMOTE 


By batch jobs 

Over the DECnet-VAX network 
By interactive processes 
By users logged in at local terminals 
By users logged in at dialup terminals 
By users logged in over a network 


A user automatically becomes a holder of one of the system-defined identifiers 
during login; that is, the VAX/VMS login software adds the appropriate 
identifier to the rights list of the process. 


The next step in this protection scheme is to define what access to grant or 
deny to the holders of each of these identifiers, for each system object that 
needs this level of protection. Since there may be more than a few identifiers 
needed to represent differing access needs for each object, it is fairly common 
to create a whole list of entries, each of which define groups of access rights 
to grant or deny. Such a list is the access control list (ACL), and each entry in 
this list is called an access control list entry (ACE). 


Just as it is possible to set up defaults for UlC-based protection on the system, 
it is possible for security managers to set up default ACLs. As a result, some 
users may not be aware their files have ACLs and may never take steps to 
change the ACLs themselves. Other users will be very actively involved in 
creating and maintaining their own ACLs. 


Because ACLs define access more precisely than the default protection code 
or than UlC-based protection, ACLs offer users the chance to fine-tune the 
action taken when access is sought to an object. You can provide an ACL on 
any object to permit as much or as little access as is desirable in each case. 
Typically, ACLs are used when you want to provide access to a system object 
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for some, but not all users, on a system. ACLs can also cause security alarms 
to be set off when access to an object succeeds or fails. 

Whenever the system receives a request for access to an object that has an 
ACL, the system searches each entry in the ACL, from the first to the last, for 
the first match it can find; it then stops searching. If another match occurs 
further down in the ACL, it will not have any effect. Thus, if you intend to 
allow one or more users greater access through a particular ACE, you should 
position that ACE at or near the top of the ACL. Even more important is the 
fact that ACEs identifying specific users should appear in the ACL before 
ACEs identifying broader classes of users. 

The use of ACLs is optional and has implications for user productivity and 
system performance. Although using ACLs can enhance the security of 
system objects in an installation through a more detailed definition of who 
is allowed what kind of access, user time must be spent in creating and 
maintaining the ACLs, and processor time is required to perform the functions 
that ACLs mandate. 


7.2.1 Creating and Maintaining an ACL 

You use the ACL Editor to create an ACL or to do extensive editing to an 
ACL. For information on the ACL Editor, see the VAX/VMS Access Control 
List Editor Reference Manual. The following DCL commands are used to 
manipulate entire ACLs or individual ACEs. 

• SET ACL 

• SET FILE/ACL 

• SET DEVICE/ACL 

• SET DIRECTORY/ACL 

The following DCL commands can be used to display ACLs: 

• SHOW ACL 

• DIRECTORY/ACL 

• DIRECTORY/FULL 

For more information on any of these DCL commands, see the individual 
command descriptions. 

You can establish ACLs for various system objects: files, directory files, global 
sections, devices, and system logical name tables. In general, you need not 
be concerned about the object type when establishing or changing an ACL; 
however, you do need to be aware of a few object-specific considerations. 
This section describes those considerations. 

Global Sections 

You must reestablish ACLs on global sections (except those backed by files) 
every time the system is booted because ACLs are not saved in any way. 

The ACL on a global section backed by a file is the ACL of the file. Changing 
the file's ACL causes the corresponding change in the global section's ACL. 
The ACL on the global section itself cannot be changed directly. 
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You can establish ACLs on both system and group global sections. Note, 
however, that if you attempt to access a group global section that is outside 
your UIC group, the operating system denies access and does not consider 
the ACL. ACLs on page frame number (PFN) and page file global sections 
may be set up and modified with the ACL Editor or with the commands: 

$ SET ACL /OBJECT_TYPE=SYSTEM_GLOBAL_SECTION section.name 
$ SET ACL /OBJECT_TYPE=GROUP_GLOBAL_SECTION section.name 

Devices 

You must reestablish ACLs on devices every time the system is booted 
because ACLs are not saved in any way. ACLs on devices are set up and 
modified with the ACL Editor or with the command: 

$ SET ACL /OBJECT_TYPE=DEVICE device-name 

Logical Name Tables 

You must reestablish ACLs on logical name tables every time the system is 
booted because they are not saved in any way. ACLs can be established for 
system logical name tables but not process logical name tables. ACLs on 
system logical name tables are set up and modified with the ACL Editor or 
with the command: 

$ SET ACL /OBJECT_TYPE=LOGICAL_NAME_TABLE table-name 


7.2.2 Access Control List Entries 

Each ACL consists of one or more ACEs. There is no limit to the number of 
ACEs that an ACL can contain, or to the number of characters in an ACE; 
however, very long ACLs increase the average amount of time necessary to 
gain access to an object. 

The type of access protection needed determines the type of ACE used in a 
given situation. There are three types of ACEs: 

• Identifier ACE — controls the type of access allowed to files, devices, 
system logical name tables, and global sections to a particular user or 
group of users. 

• Default protection ACE — defines the default protection for a directory, 
so that the protection can be propagated to the files and subdirectories 
created in that directory. (This type of ACE is applicable only to directory 
files.) 

• Security Alarm ACE — provides a security alarm when a file, directory, or 
global section is accessed in a particular way. 

The exact format of an ACE depends on its type, but all ACEs are enclosed in 
parentheses. In general, the format of an ACE is the following: 

(type[.options][,access_to_grant]) 
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7.2.3 Identifier ACEs 


An identifier ACE controls the types of access allowed to specific users based 
on the user's identification. The format for an identifier ACE is 

(IDENTIFIER=identifier[,options][.access] ) 

The first field in the identifier ACE consists of the keyword IDENTIFIER, 
followed by one or more identifiers. An identifier can be 

• The user identification code (UIC) 

• A general identifier established by the system manager in the system 
rights database 

• A system-defined identifier 

In general, you should regard the six system-defined identifiers (BATCH, 
NETWORK, INTERACTIVE, LOCAL, DIALUP, and REMOTE) as mutually 
exclusive; you should not attempt to use them in combination with each 
other. However, you may combine them when specifying multiple identifiers, 
by connecting them with plus signs ( + ). 

The system takes the access action you include in the ACE only for the user 
who matches all the identifiers. For example, if you wanted to grant read 
access to user [301,25] running a batch job, you would specify the identifier 
ACE as 

(IDENTIFIER*[301.26]+BATCH,ACCESSPREAD) 

Although it is not common practice for a number of users to share the same 
UIC, it is likely that a number of users will share the same general identifier. 
Users with the same general identifier do not need to be in the same UIC- 
based group. Furthermore, a single user can be associated with a number of 
different general identifiers as defined in the rights database. Because this is 
the case, the creator of an ACL has considerable flexibility in selecting sets of 
users and defining access capabilities for them. 

For example, the user identified by the UIC [301,25] is a member of the UIC- 
based group 301. That user may be the only member of group 301 who is 
also associated with the general identifier PERSONNEL. An ACE that defines 
a particular type of access for the users associated with the general identifier 
PERSONNEL grants that access to that user, but not to the other members of 
group 301. 


7.2.3.1 Specifying Options in Identifier ACEs 

The options field in an identifier ACE controls whether an ACE is propagated 
and whether it can be displayed or deleted. This field in an identifier ACE 
begins with the keyword OPTIONS, and takes one or more of the following 
keywords: 


7-13 







Protection 


7.23.2 


7.2.3.3 


DEFAULT Indicates that an ACE is to be included in the ACL of 

any files created within a directory. When the ACE is 
propagated, the DEFAULT indicator is removed from the 
ACL of the created file. This option is valid only for directory 
files. A default ACE does not grant or deny access; it just 
affects the ACL of newly created files. 

HIDDEN Indicates that this ACE should only be changed by the 

application that added it. The ACL Editor will not permit 
modification or deletion. Thus, the ACL Editor displays the 
ACE only to show its relative position within the ACL, not to 
facilitate editing of the ACE. Also, DIRECTORY and SHOW 
ACL will not display the ACE. 

PROTECTED Indicates that an ACE will be preserved even when an 

attempt is made to delete the entire ACL. A protected 
ACE must be specifically deleted with the ACL Editor or by 
specifying the ACE on the command line of one of the DCL 
commands for ACLs. 

NOPROPAGATE Indicates that when the ACL is copied from one version 
of a file to a later version of the same file, the ACE is not 
propagated. 

NONE Indicates that no options apply to an ACE. Although you 

may enter OPTIONS=NONE when you create the ACE, 
OPTIONS=NONE is not displayed when the ACE is displayed. 


Multiple options must be connected by plus signs ( + ). If you specify any 
other options with the NONE option, the other option(s) will take precedence. 


Specifying Access in Identifier ACEs 

The third field in an identifier ACE specifies what type of access you are 
allowing the user(s) identified in the first field of the ACE. This field begins 
with the keyword ACCESS followed by a string of access actions connected 
by plus signs ( + ). The following types of access are allowed in an identifier 
ACE: 


READ 

WRITE 

EXECUTE 

DELETE 

CONTROL 

NONE 


Accessor can read a file, read from a disk, or allocate a 
device 

Accessor can read or write a file 

Accessor can execute an image file, look up entries in a 
directory without using wildcard characters 

Accessor can delete a file 

Accessor has all the privileges of the object's actual owner 
Accessor has no access to the object 


Sample Identifier ACEs 
Identifier ACE for a File 

The most common type of ACL is one that defines the access to a file for 
a group of users. In the following sample ACL, access to a file is based on 
the identity of a user. PERSONNEL, SECURITY, and SECRETARIES are 
general identifiers that have been assigned to appropriate sets of users by the 
system manager using the Authorize Utility. NETWORK is a system-defined 
identifier, while [20,*] and [SALESJONES] are examples of UIC identifiers. 
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(IDENTIFIER=SECURITY,OPTIONS=PEOTECTED.ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL) 

(IDENTIFIER=PERSONNEL,ACCESS=READ+WRITE+EXECUTE+DELETE) 

(IDENTIFIER=SECRETARIES.ACCESS=READ+WRITE) 

(IDENTIFIER 3 [20,*],ACCESS=READ) 

(IDENTIFIER=NETWORK,ACCESS^NONE) 

(IDENTIFIER=[SALES.JONES].ACCESS=NONE) 

In the preceding example, the ACE that provides the greatest amount of 
file access is first in the list. In this way, if one of the users has both the 
SECURITY and PERSONNEL identifiers, the user obtains the maximum 
access rights through the first match, which is the SECURITY identifier. In 
this example, the user with UIC [SALES,JONES] will be prohibited from any 
access to the file, unless that user also happens to have one of the general 
identifiers, which is probably an oversight on the part of the creator of the 
ACL. If the ACL creator wants to be absolutely certain that the user with UIC 
[SALESJONES] cannot possibly gain access to the file, the ACE that is at the 
bottom of the ACL should be moved to the top. 

Notice also that the order of the ACEs in the example above permits a 
number of users to gain types of file access over the DECnet-VAX network. 
The users with the identifiers of SECURITY, PERSONNEL, SECRETARIES, 
and UIC [20,*] can all gain some access over the network, although only 
those with the identifier SECURITY can gain full access. All other users are 
prohibited from network access due to the fifth ACE. While this may well be 
the intent of the ACL creator, it would be an unfortunate oversight if it were 
not. Always take special care in ordering the ACEs within your ACLs. 

The only ACE that includes an option field is the first ACE, which contains 
the PROTECTED option. Use of this option guarantees that the first ACE 
will not be deleted, unless it is explicitly specified with the SET FILE/ACL 
/DELETE command or deleted using the ACL Editor. 

Identifier ACE for a Directory 

The OPTIONSHDEFAULT option of an identifier ACE allows users to define 
one or more default ACEs for inclusion in the ACLs for files created in a 
particular directory. A default ACE is supplied for all new files created in 
that directory; any existing files are not supplied with the default ACE. Thus, 
if you wanted all files in the directory [MALCOLM] to have an ACE that 
permitted read and write access to users with the PERSONNEL identifier, you 
could include the following ACE in the ACL for the file MALCOLM.DIR: 

(IDENTIFIER=PERSONNEL.0PTI0NS=DEFAULT,ACCESS=READ+WRITE) 

As a result of this ACE, any file created in the [MALCOLM] directory has the 
following ACE: 

(IDENTIFIER=PERSONNEL.ACCESS=READ+WRITE) 

Notice that the DEFAULT option does not appear in the file's ACE. However, 
any subdirectory created in the [MALCOLM] directory has the DEFAULT 
option as part of its ACE so that the default ACE can be propagated 
throughout the entire directory tree. 

You may also define an identifier ACE to restrict access to the directory file 
itself. 

Note: ACEs with the DEFAULT option are not used in protection checks of the 
directory file. 
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Identifier ACE for a Device or System Logical Name Table 

Identifier ACEs for devices and system logical name tables are created in the 
same manner as other ACEs. 

The following example creates a system logical name table named 
INTERNATIONAL and grants exclusive delete access to the user DESCH. 

In order to create a system logical name table, you must have SYSPRV 
privilege and E (enable) access to the system logical name table. 

$ CREATE/NAME.TABLE INTERNATIONAL/PARENT_TABLE=LNM$SYSTEM_DIRECTORY - 
_$/PROT=(S:RWE, 0:RWE, G:RW)/QU0TA=500 

$ SET ACL/ACL=(IDENTIFIER=DESCH, ACCESS=DELETE) - 
_$ /OBJECT_TYPE=LOGICAL_NAME_TABLE INTERNATIONAL 

For example, suppose your company has a special letter-quality printer 
(TTA8) that is used only for printing checks. As a result, the check forms 
are always loaded in the printer. This device is never to be used for logins, 
and no queues are directed to it. Only one user, MGREY, is allowed read 
and write access to it. The system manager can accomplish this restriction by 
setting the protection on the printer with the command: 

$ SET PROTECTIONS,0,G,W)/DEVICE TTA8: 

Then, the following identifier ACE, applied to the object TTA8, restricts access 
to the device: 

(IDENTIFIER-MGREY,ACCESS Z READ+WRITE) 


7.2.4 Default Protection ACEs 

The default protection ACE is used to ensure that a particular type of UIC- 
based protection is propagated throughout a directory tree. This type of ACE 
allows you to specify protection for a particular directory structure that is 
different from the default protection applied to other directories. Default 
protection ACEs can be applied only to directory files. 

The format for a default protection ACE is as follows: 

(DEFAULT_PROTECTION[,options],protection_mask) 

This type of ACE is specified by the keyword DEFAULT-PROTECTION. As 
in the identifier type of ACE, the second field in a default protection ACE, 
the options field, controls whether an ACE is propagated, can be displayed, 
or can be deleted. This field in a default protection ACE begins with the 
keyword OPTIONS and takes one or more of the following keywords: 

HIDDEN Indicates that this ACE should only be changed by the 

application that added it. The ACL Editor will not permit 
modification or deletion. Thus, the ACL Editor displays the 
ACE only to show its relative position within the ACL, not 
to facilitate editing of the ACE. The DCL DIRECTORY and 
SHOW ACL commands will not display hidden ACEs. 

PROTECTED Indicates that an ACE will be preserved even when an 

attempt is made to delete the entire ACL. A protected 
ACE must be specifically deleted with the ACL Editor or by 
specifying the ACE on the command line of one of the ACL 
DCL commands. 


v * . 
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NOPROPAGATE Indicates that when copying an ACL from one version of 
a file to a later version of the same file, the ACE is not 
propagated. 

NONE Indicates that no options apply to an ACE. Although you 

may enter OPTIONSHMONE when you create the ACE, 
OPTIONS=NONE is not displayed when the ACE is displayed. 

Multiple options are connected by plus signs ( + ). If you specify any other 
options with the NONE option, the other options will take precedence. 

The protection mask is specified the same as for UlC-based protection 
with the user categories — SYSTEM, WORLD, GROUP, and OWNER — 
and the access categories — READ, WRITE, EXECUTE, and DELETE. See 
Section 7.1.1 for more information. 

The following ACE, included in an ACL for the directory [MALCOLM], sets 
up default protection so that any files created in the directory will allow the 
system and owner groups read, write, execute, and delete access and the 
group and world groups no access: 

(DEFAULT.PROTECTION,S:RWED.0:RWED) 

Note that when you add or change the default protection for a directory, 
there is no effect on the files already created in the directory; however, all 
new files created in the future will receive the default protection. 


7.2.5 Security Alarm ACEs 

The security alarm ACE allows you to specify that an alarm message be 
sent to the security operator's terminal if a certain type of access takes place. 
Whenever it is important that some response be taken when an object has 
been accessed in a particular way, you should consider adding a security 
alarm ACE to the object's ACL. 

The security alarm functions only when the alarms to operators enabled 
as security operators have been enabled through the DCL command SET 
AUDIT. 

Although you can independently create alarm ACEs in an ACL, causing 
the system to observe the event and take the required action, you should 
coordinate this with your system's security manager (the person who 
possesses the SECURITY privilege). The security manager is responsible 
for enabling the alarm feature. Since this feature uses system resources, the 
security manager may be reluctant to leave it enabled at all times. 

The format of a security alarm ACE is as follows: 

(ALARM.JOURNAL=SECURITY [. options] [, access] ) 

This type of ACE is specified by the keywords ALARM— 
JOURNAL=SECURITY. As in the IDENTIFIER type of ACE, the second 
field in security alarm ACE begins with the keyword OPTIONS, which takes 
one or more of the following keywords: 
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DEFAULT 


HIDDEN 


PROTECTED 


NOPROPAGATE 

NONE 



Indicates that an ACE is to be included in the ACL of any 
files created within a directory. The DEFAULT indicator is 
removed from the ACE of the created file. This option is 
valid only for directory files. A default ACE does not grant 
or deny access; it just affects the ACL of newly created files. 

Indicates that this ACE should only be changed by the 
application that added it. The ACL Editor will not permit 
modification or deletion. Thus, the ACL Editor displays the 
ACE only to show its relative position within the ACL, not to 
facilitate editing of the ACE. Also, DIRECTORY and SHOW 
ACL will not display the ACE. 

Indicates that this ACE will be preserved even when an 
attempt is made to delete the entire ACL. A protected 
ACE must be explicitly deleted with the ACL Editor or by 
specifying the ACE on the command line of one of the DCL 
commands for ACLs. 

Indicates that when the ACL is copied from one version 
of a file to a later version of the same file, the ACE is not 
propagated. 

Indicates that no options apply to this ACE. Although 
you enter OPTIONS=NONE when you create the ACE, 
OPTIONS=NONE is not displayed when the ACE is displayed. 



Multiple options are connected by plus signs ( + ). If you specify any other 
options when specifying NONE, the other options take precedence. 


The third field in an alarm ACE controls the type of access that causes the 
alarm to be sent. You can specify any of the following access actions with the 
ACCESS keyword: 


READ 

WRITE 

EXECUTE 

DELETE 

CONTROL 

SUCCESS 


Generates an alarm if an accessor attempts to read the 
object 


Generates an alarm 
write the object 


if an accessor attempts to read or to 


Generates an alarm 
object 


if an accessor attempts to execute the 


Generates an alarm if an accessor attempts to delete the 
object 

Generates an alarm if an accessor attempts to perform 
control operations on the object, such as changing the 
protection on the object 

Generates an alarm for each successful attempt by an 
accessor to access the object with any of the access- 
allowed-mask entries from the set above 


FAILURE Generates an alarm for each unsuccessful attempt by an 

accessor to access the object with any of the access- 
allowed-mask entries from the set above 


For an alarm to have any effect, you must include either SUCCESS or 
FAILURE, or both. 
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protection* 7-2 


3-7 


Date 

See also Absolute time 
entering in commands*2-13 
DCL (DIGITAL Command Language) 
interactive mode* 1-1 
noninteractive mode* 1-1 
DCL command 
See Command 
Default 

device name designation *3-12 

file type *3-3, 3-4 

for file specification *3-2 

job logical names *4-5 

process directory logical names *4-7 

process logical names *4-4 

protection • 7-7 

system directory logical names *4-8 
system logical names *4-6 
temporary • 2-6 

in output file *3-18 
values for qualifiers • 2-7 
Default protection ACE *7-12, 7-16 
DEFINE KEY command* 1-10 
DELETE key* 1-7 


E 


Ellipsis (...) 

as directory searching character *3-16, 3-17 
used to specify output directory • 3-19, 3-20, 
3-21 

.EQ. logical operator*5-13 
.EQS. logical operator*5-14 
Evaluation 

automatically performed by command 
interpreter* 6-1 

of operator in expression • 5-10 
of symbol *6-1 
Expression 

changing context of *5-8 
character string *5-9 

equating to symbol *5-9 
implicit conversion in *5-8 
iterative subtitution in • 6-7 
operators in *5-10 
rules for determining mode of* 5-7 
summary of operators*5-10 
use of arithmetic comparison operators in *5-13 
use of arithmetic operators in *5-12 
use of logical operators in *5-12 
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Expression (cont'd.) File version number• 3-3 

use of string comparison operators in • 5-14 Foreign command *5-19 

use of string operators in • 5-9 Foreign file specification string *3-14 


F G 


FSINTEGER lexical function 

to change context of expression • 5-8 
FSSTRING lexical function 

to change context of expression • 5-8 
File 

output file qualifiers *2-10, 2-12 
protection • 7-2 
qualifier values *2-10 
temporary input file defaults 0 2-6 
File access 

category summary *7-3 
delete* 7-4 
execute* 7-4 
read* 7-4 
write* 7-4 
File name*3-3 

alternate form for magnetic tapes *3-5 
null *3-5 
File protection 

and RENAME command *7-7 
changing* 7-6 
changing default *7-7 
default disk*7-7 
of tape volumes • 7-9 
File specification *3-1, 3-2, 3-3 
See also Device 
See also Directory 
See also File name 
See also File type 
See also File version number 
See also Node name 
default • 3-2 

and logical name *4-12 
entering • 2-5 
example* 3-2 
foreign *3-13, 3-14 
format • 3-1 
node name *3-13 

See also Node name 
parameters* 2-5 

task specification string *3-13, 3-14 
File type *3-3 
default• 3-3, 3-4 
null *3-5 


.GE. logical operator*5-13 
.GES. logical operator*5-14 
Global symbol 

reserved by DIGITAL *5-2 
$RESTART • 5-2 
SSEVERITY • 5-2 
SSTATUS • 5-2 
GST (global symbol table) 

in command interpreter search *5-3 
.GT. logical operator • 5-13 
.GTS. logical operator*5-14 


H 


Help* 1-5 

HELP command* 1-5 
Hexadecimal value *5-16 
Hyphen (-) 

as directory searching character • 3-18 


i 


Identifier ACE *7-12, 7-13 
example*7-14, 7-15 
specifying access *7-14 
specifying identifiers*7-13 
specifying options *7-13 
Implicit conversion 

in string comparison operation • 5-8 
of operands in expression • 5-8 
Input file 

temporary default *2-6 
Integer 

calculation in arithmetic operation • 5-12 
implicit conversion to string *5-8 
Iterative substitution • 6-5 
in expression • 6-7 
using apostrophes • 6-6 
using command synonyms *6-6 
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J 


Job 

default logical name *4-5 


Logical name table (cont'd.) 

how to display *4-3 
Logical operation *5-12 
operands for*5-13 
Login command procedure* 1-2 
LT. logical operator*5-13 
.LTS. logical operator • 5-14 



Key 

defining a • 1-10 
Keyword 

abbreviating *2-3, 2-4 


M 


Message 
format • 1 -4 
Mode 

rules for determination in expression • 5-7 


L 


.LE. logical operator*5-13 
.LES. logical operator*5-14 
Lexical function 

to change context of expression • 5-8 
Line editing 

function keys* 1-5 
Local symbol table 

in command interpreter search *5-3 
Logical name *4-1, 4-3, 4-4, 4-5, 4-6, 4-7, 4-8, 
4-9, 4-10, 4-11, 4-12, 4-13, 4-22 
access modes *4-9 
and concealed device *4-12 
attributes *4-9 
default job *4-5 
default process • 4-4 
default process directory • 4-7 
default system • 4-6 
default system directory • 4-8 
for process permanent file *4-22 
in input file list *4-13 
job table *4-15 
quota *4-15 

preventing iterative translation *4-12 

specifying • 4-1 

table 

quota *4-14 
shareable *4-14 
translation *4-10, 4-11,4-12 
defaults *4-12 
iterative *4-1 1 

used to determine output file specification* 
2-12 

Logical name table *4-4 


N 


.NE. logical operator*5-13 
.NES. logical operator*5-14 
Network node 
See Node name 
Node name *3-13 

access control string *3-13 
Null file name *3-5 
Null file type *3-5 



Offset 

definition of • 5-16 
Operator 

arithmetic *5-12 
arithmetic comparison • 5-13 
in expression *5-10 
logical *5-12 

precedence of evaluation • 5-10 
string • 5-9 

string comparison • 5-14 
Output file 

entering qualifiers*2-10, 2-12 
temporary default *3-18 
Output file qualifiers 
entering *2-10, 2-12 
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P 


Parameter 

abbreviating* 2-4 
command 

entering *2-2 
file specification • 2-5 
qualifier 

entering • 2-7 
Password 

entering • 1-2 
secondary* 1-2 
system • 1-2 
Percent sign (%) 

as wildcard character*3-16 
PRINT command* 1-3 
Privilege* 1-11 
process* 1-11 
Process 

default characteristics* 1-1 
default logical name *4-4 
privileges* 1-11 
Process permanent file 

default logical name *4-22 
Prompt 

for DCL command* 1-4 
Protection • 7-1 

access category *7-3 

and RENAME command *7-7 

changing* 7-6 

changing default *7-7 

default • 7-7 

directory file*7-7 

effect of privileges*7-5 

of directories*7-8 

of disk file*7-6 

of files • 7-2 

of tape files*7-9 

of tape volumes *7-9 

of volumes*7-2 

specifying • 7-5 

UlC-based • 7-2 


Q 


Qualifier 

abbreviating • 2-4 
command qualifier • 2-7 
default values • 2-7 


Qualifier (cont'd.) 
entering • 2-6 
file qualifier*2-7 
entering • 2-7 
parameter 

entering • 2-7 
specifying • 2-10, 2-12 
Qualifier value 

abbreviating • 2-4 
specifying *2-10 
Quota* 1-11, 1-12 

logical name table *4-14 
job *4-15 



RECALL command* 1-9 
RENAME command 

and file protection • 7-7 
Repetitive substitution • 6-5 
$RESTART • 5-2 



Security alarm ACE *7-12, 7-17 
specifying access *7-18 
specifying options *7-17 
Security feature 

accessing the system* 1-2 
SET PROTECTION/DEFAULT command *7-7 
SET PROTECTION command *7-6 
SET TERMINAL command* 1-5 
$SEVERITY • 5-2 
SHOW LOGICAL command *4-3 
SHOW SYMBOL command 
to show symbol value *5-3 
SHOW TERMINAL command* 1-5 
Special-purpose string assignment statement • 5-4 
SSTATUS • 5-2 
String 

automatic evaluation by command interpreter* 
6-1 

concatenation • 5-9 
expression* 5-9 

implicit conversion to integer *5-8 
reduction • 5-9 

special-purpose assignment • 5-4 
String assignment statement 
format • 5-9 
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String assignment statement (cont'd.) 
space and tab removal*5-4 
special purpose format *5-4 
uppercase conversion • 5-4 
String comparison operation • 5-14 
implicit conversion in *5-8 
operands for*5-15 
String concatenation operator (+) • 5-9 
String operation • 5-9 
operands for* 5-11 
String reduction operator (-) • 5-9 
Subdirectory 
See Directory 
Substitution 

iterative *6-5, 6-6 

of symbols in command procedure • 6-1 
of symbols within character string *6-3 
repetitive* 6-5 
Substitution operator 

ampersand (&) used as *6-3 
apostrophe (') used as *6-2 
Symbol 

automatic evaluation of *6-1 
defining with DCL* 1-10 
definition* 5-1 
Symbol name*5-1 

assignments to character string expression • 5-4 

assignment to character string expression • 5-4 

binary overlay in *5-17 

change context of *5-6 

function in commnad procedure*5-1 

iterative replacement in expression • 6-7 

iterative substitution • 6-5 

repetitive substitution *6-5 

rules for forming • 5-1 

substitution 

in character string • 6-3 
performed by command interpreter*6-5 
using ampersand • 6-3 
using apostrophe • 6-2 
undefined • 6-8 

use of offset in substring replacement*5-16 
Symbol substitution 

automatic evaluation • 6-1 
in command procedure*6-1 
Symbol table 

order of search by command interpreter*5-3 
search order during symbol substitution • 5-3 
SYS$L0GIN • 4-5 
SYS$LOGIN_DEVICE • 4-5 
SYS$REM_ID • 4-5 
SYS$REM_NODE • 4-5 


SYS$SCRATCH • 4-5 
System message 
format • 1 -4 


T 


Tape 

protection • 7-2, 7-9 
Task specification string *3-13, 3-14 
Terminal characteristics 
setting* 1-5 

Terminal function key* 1-5, 1-7 
BACKSPACE key* 1-8 
CTRL/C* 1-8 
CTRL/U* 1-8 
CTRL/Y* 1-8 
DELETE key* 1-7 
Time 

See also Absolute time 
See also Delta time 

absolute and delta combinations *2-15 
entering in commands*2-13 


u 


UAF (user authorization file)* 1-1 
UIC (user identification code)* 1-1 
alphanumeric format*7-2 
numeric format • 7-2 
specifying* 7-2 
Undefined symbol *6-8 
User authorization file 
See UAF 

User identification code 
See UIC 


v 


Volume 

protection*7-2, 7-9 


w 


Wildcard character*3-14, 3-15, 3-16, 3-17, 3-18, 
3-19, 3-20, 3-21 
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Wildcard character (cont'd.) 
asterisk (*)*3-19, 3-20, 3-21 
ellipsis (...)*3-19, 3-20, 3-21 
hyphen (-) • 3-18 

in input file specifications*3-14, 3-15, 3-16 
percent sign (%)*3-16 
used to search directory • 3-16 
used to specify output directory *3-19, 3-20, 
3-21 

use to search directory • 3-17, 3-18 
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